doxygennamespace Directive#

This directive generates the appropriate output for the contents of a namespace.

It takes the standard project, path, outline and no-link options and additionally the content-only, desc-only, members, protected-members, private-members and undoc-members options.

content-only: If this flag is specified, then the directive does not output the name of the namespace or the namespace description and instead outputs the contents of the namespace. This can be useful for structuring your documentation but leaving out the namespace declaration itself which is often undocumented.
desc-only: If specified, only the description and name of the namespace will be displayed.
members: If specified, the public members of any classes in the namespace output will be displayed. Unlike the doxygenclass members option, this does not optionally take a list of member names to display as this will be applied across multiple classes within the namespace.
protected-members: If specified, the protected members of any classes in the namespace output will be displayed.
private-members: If specified, the private members of any classes in the namespace output will be displayed.
undoc-members: If specified, the undocumented members of any classes in the namespace output will be displayed provided the appropriate members or private-members options are specified as well.

If you would like to always specify some combination of members, protected-members, private-members and undoc-members then you can use the breathe_default_members configuration variable to set it in the conf.py.

Basic Example#

The plain doxygennamespace directive will output the namespace name and description and any top level publicly visible members of the namespace.

.. doxygennamespace:: foo
   :project: namespace

It produces this output:

namespace foo#

Functions

int baz()#: This also appears.

class Bar#: #include <namespacefile.h>

This appears in the documentation.

namespace ns#

More examples in a nested namespace.

Typedefs

typedef int MyInt#

Enums

enum Letters#

Values:

enumerator A#: A documented enumeration constant.

enumerator B#

enumerator C#

class FooClass#

struct FooStruct#: #include <namespacefile.h>

Documentation here.

Content-Only Example#

The content-only option changes the output to only include the content of the namespace and not the namespace name or description. So this:

.. doxygennamespace:: foo
   :project: namespace
   :content-only:

Produces this output:

int foo::baz(): This also appears.

class Bar: #include <namespacefile.h>

This appears in the documentation.

Note

As you can see from the output, section headings like ‘Functions’ are missing from the :content-only: display. This is due to an implementation detail. Open an issue on github if you’d like it addressed.

Members Example#

The members option changes the output to include the public members of any classes. The output for any class in the namespace should be the same as if it had be produced by the doxygenclass directive with the members option specified.

.. doxygennamespace:: foo
   :project: namespace
   :members:

It produces this output:

namespace foo

Functions

int baz(): This also appears.

class Bar

#include <namespacefile.h>

This appears in the documentation.

Public Functions

virtual void publicFunction() const = 0: namespaced class function

class PublicClass: #include <namespacefile.h>

A protected class.

class UndocumentedPublicClass

namespace ns

More examples in a nested namespace.

Typedefs

typedef int MyInt

Enums

enum Letters

Values:

enumerator A: A documented enumeration constant.

enumerator B

enumerator C

class FooClass

struct FooStruct: #include <namespacefile.h>

Documentation here.

Protected Members Example#

The protected-members option changes the output to include the protected members of any classes. The output for any class in the namespace should be the same as if it had be produced by the doxygenclass directive with the protected-members option specified.

.. doxygennamespace:: foo
   :project: namespace
   :protected-members:

It produces this output:

namespace foo

Functions

int baz(): This also appears.

class Bar

#include <namespacefile.h>

This appears in the documentation.

Protected Functions

inline void protectedFunction(): A protected function.

class ProtectedClass: #include <namespacefile.h>

A protected class.

class UndocumentedProtectedClass

namespace ns

More examples in a nested namespace.

Typedefs

typedef int MyInt

Enums

enum Letters

Values:

enumerator A: A documented enumeration constant.

enumerator B

enumerator C

class FooClass

struct FooStruct: #include <namespacefile.h>

Documentation here.

Private-Members Example#

The private-members option changes the output to include the private members of any classes. The output for any class in the namespace should be the same as if it had be produced by the doxygenclass directive with the private-members option specified.

.. doxygennamespace:: foo
   :project: namespace
   :private-members:

Produces this output:

namespace foo

Functions

int baz(): This also appears.

class Bar

#include <namespacefile.h>

This appears in the documentation.

Private Functions

virtual void privateFunction() const = 0: This is a private function.

class PrivateClass: A private class.

class UndocumentedPrivateClass

namespace ns

More examples in a nested namespace.

Typedefs

typedef int MyInt

Enums

enum Letters

Values:

enumerator A: A documented enumeration constant.

enumerator B

enumerator C

class FooClass

class InnerFoo

struct FooStruct: #include <namespacefile.h>

Documentation here.

Undocumented Members Example#

The undoc-members option changes the output to include any undocumentated members from the sections (public, protected, private) that are being displayed for the classes in the namespace output.

.. doxygennamespace:: foo
   :project: namespace
   :private-members:
   :undoc-members:

Produces this output:

namespace foo

Functions

int baz(): This also appears.

class Bar

#include <namespacefile.h>

This appears in the documentation.

Private Functions

virtual void privateFunction() const = 0: This is a private function.

virtual void undocumentedPrivateFunction() const = 0

class PrivateClass: A private class.

class UndocumentedPrivateClass

namespace ns

More examples in a nested namespace.

Typedefs

typedef int MyInt

Enums

enum Letters

Values:

enumerator A: A documented enumeration constant.

enumerator B

enumerator C

class FooClass

class InnerFoo

struct FooStruct: #include <namespacefile.h>

Documentation here.

Note

Undocumented classes are still not shown in the output due to an implementation issue. Please post an issue on github if you would like this resolved.

Outline Example#

This displays only the names of the members of the namespace and not their documentation. The other options determine which members are displayed.

.. doxygennamespace:: foo
   :project: namespace
   :members:
   :outline:

It produces this output:

namespace foo

Functions

int baz()

class Bar

Public Functions

virtual void publicFunction() const = 0

class PublicClass

class UndocumentedPublicClass

namespace ns

Typedefs

typedef int MyInt

Enums

enum Letters

Values:

enumerator A

enumerator B

enumerator C

class FooClass

struct FooStruct

Nested Example#

The referenced namespace can be nested in another namespace.

.. doxygennamespace:: foo::ns
   :project: namespace

Produces this output:

namespace ns

More examples in a nested namespace.

Typedefs

typedef int MyInt

Enums

enum Letters

Values:

enumerator A: A documented enumeration constant.

enumerator B

enumerator C

class FooClass

struct FooStruct: #include <namespacefile.h>

Documentation here.

Failing Example#

This intentionally fails:

.. doxygennamespace:: madeupnamespace
   :project: namespace

It produces the following warning message:

Warning

doxygennamespace: Cannot find namespace “madeupnamespace” in doxygen xml output for project “namespace” from directory: ../../examples/specific/namespacefile/xml/