Request: C++ namespace as an entity

[ZedThree]

Is your feature request related to a problem? Please describe.

Currently, breathe uses cpp:type to render namespaces. This means that opening the same namespace in multiple files results in a "duplicate declaration" warning.

Unfortunately, the cpp:namespace directive is already taken as a way of changing scope for name resolution, and doesn't actually render anything. This means that there isn't really a suitable directive for the namespace entity.

Describe the solution you'd like

Perhaps one of these options:

1. a new directive in the cpp domain for namespace entities. Naming this seems like a bit of a challenge, maybe cpp:ns or similar;
2. an option on the existing cpp:namespace to cause it to be rendered, :render: or :show: perhaps.

This would allow breathe to switch to one of those directives for namespace nodes and avoid false "duplicate declaration" warnings.

Describe alternatives you've considered

An alternative would be to change breathe to keep the namespace as part of the entity name, or use some other means of rendering it. It looks like breathe is currently not actively maintained, so I'm not sure how difficult or possible this change would be.

[picnixz]

IIUC, .. cpp:namespace:: foo makes you assume that the objects you are documenting afterwards are assumed to be part of the foo namespace ?

If so, I personally think that it wasn't the best idea and

I don't want to have a name such as cpp:ns because it's not really clear that it's something for documenting a namespace.

Instead, I think we should entirely change the directive itself. I know that this will be a breaking change, but honestly, if I read something like .. cpp:namespace:: foo, for me it means "hey I am now documenting the foo namespace" and not "well here I assume that I am in the foo scope". Especially if the argument of the directive can be any kind of scope.

Thus, I suggest renaming the current cpp:namespace to cpp:scope since this semantically reflects what we are doing (the notion of a scope being broader than just namespaces).

[electric-coder]

Naming this seems like a bit of a challenge, maybe cpp:ns or similar

I'm not a C++ expert but there's a precedent for names clashing between reStructuredText and CSS in Sphinx, so just for reference:

Directives

• Special directives

class (assign a class attribute to the next element)

Note

When the default domain contains a class directive, this directive will be shadowed. Therefore, Sphinx re-exports it as rst-class.

So there ended up being a .. class:: and a .. rst-class:: directives.

[picnixz]

@jakobandersen @AA-Turner what are you thoughts on this one?