doxygenclass Directive

This directive generates the appropriate output for a single class. It takes the standard project, path, outline and no-link options and additionally the members, protected-members, private-members, undoc-members, membergroups and members-only options.

members

Designed to behavior in a similar manner to the members option for the autoclass directive that comes with the Sphinx autodoc extension.

If you do not specify this option you will not get any information about the class members, just the general class documentation. If you provide it without arguments, then Breathe adds all the public members and their documentation. If you specify it with comma separated arguments, then Breathe will treat the arguments as names of members and provide documentation for only those members that have been named.

protected-members

If specified, the protected members of the class will be displayed.

private-members

If specified, the private members of the class will be displayed.

undoc-members

If specified, the undocumented members of the class will be displayed.

membergroups

If specified, only the groups in a space-delimited list following this directive will be displayed.

members-only

This will allow to show only the members, not the class information. Child classes and structs are also not shown.

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.

The output includes references to any base classes and derived classes of the specified class.

Basic Example

This displays the class documentation without any members:

.. doxygenclass:: Nutshell
   :project: nutshell

It produces this output:

class Nutshell

With a little bit of a elaboration, should you feel it necessary.

Template Specialisation Example

You can reference class template specialisations by include the specialisation in the name:

.. doxygenclass:: TemplateClass< T * >
   :project: template_specialisation

Produces this output:

template<typename T>
class TemplateClass<T*>

A partial specialization of TemplateClass for pointer types.

Where as without the specialisation, the directive references the generic declaration:

.. doxygenclass:: TemplateClass
   :project: template_specialisation

Produces this output:

template<typename T>
class TemplateClass

A generic template class.

Note the spacing inside the <>, it’s important: there must be a space after the < and before the >.

Members Example

This directive call will display the class documentation with all the public members:

.. doxygenclass:: Nutshell
   :project: nutshell
   :members:

It produces this output:

class Nutshell

With a little bit of a elaboration, should you feel it necessary.

Public Types

enum Tool

Our tool set.

The various tools we can opt to use to crack this particular nut

Values:

enumerator kHammer

What? It does the job.

enumerator kNutCrackers

Boring.

enumerator kNinjaThrowingStars

Stealthy.

Public Functions

Nutshell()

Nutshell constructor.

~Nutshell()

Nutshell destructor.

void crack(Tool tool)

Crack that shell with specified tool

Parameters:

tool – the tool with which to crack the nut

bool isCracked()

Returns:

Whether or not the nut is cracked

Specific Members Example

This displays the class documentation with only the members listed in the :members: option:

.. doxygenclass:: Nutshell
   :project: nutshell
   :members: Tool, crack, isCracked

It produces this output:

class Nutshell

With a little bit of a elaboration, should you feel it necessary.

Public Types

enum Tool

Our tool set.

The various tools we can opt to use to crack this particular nut

Values:

enumerator kHammer

What? It does the job.

enumerator kNutCrackers

Boring.

enumerator kNinjaThrowingStars

Stealthy.

Public Functions

void crack(Tool tool)

Crack that shell with specified tool

Parameters:

tool – the tool with which to crack the nut

bool isCracked()

Returns:

Whether or not the nut is cracked

Protected Members

This displays only the protected members of the class. Normally this is combined with the :members: option to show the public members as well.

.. doxygenclass:: GroupedClassTest
   :project: group
   :protected-members:

It produces this output:

class GroupedClassTest

first class inside of namespace

Protected Functions

inline void protectedFunction()

A protected function.

class ProtectedClass

A protected class.

class UndocumentedProtectedClass

Private Members

This displays only the private members of the class. Normally this is combined with the :members: option to show the public members as well.

.. doxygenclass:: Nutshell
   :project: nutshell
   :private-members:

It produces this output:

class Nutshell

With a little bit of a elaboration, should you feel it necessary.

Private Members

bool m_isCracked

Our cracked state.

Undocumented Members

This displays the undocumented members of the class which are suppressed by default. Undocumented public members are only shown if the :members: option is also used. The same goes for the undocumented private members and the private-members option.

.. doxygenclass:: ClassTest
   :project: class
   :members:
   :private-members:
   :undoc-members:

It produces this output:

class ClassTest

class outside of namespace

Public Functions

void function(int myParameter)

non-namespaced class function

More details in the header file.

More documentation in the impl file

void anotherFunction()

non-namespaced class other function

More documentation in the impl file

virtual void publicFunction() const = 0

namespaced class function

virtual void undocumentedPublicFunction() const = 0

Private Functions

virtual void privateFunction() const = 0

This is a private function.

virtual void undocumentedPrivateFunction() const = 0

class PrivateClass

A private class.

struct PrivateStruct

A private struct.

class PublicClass

A public class.

struct PublicStruct

A public struct.

class UndocumentedPrivateClass

struct UndocumentedPrivateStruct

class UndocumentedPublicClass

struct UndocumentedPublicStruct

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.

Membergroups

This will show only members in the specified member group(s).

.. doxygenclass:: GroupedMembers
   :project: membergroups
   :members:
   :membergroups: myGroup

It produces this output:

class GroupedMembers

demonstrates member groups

myGroup

void in_mygroup_one(int myParameter)

A function.

void in_mygroup_two(int myParameter)

Another function.

Without :membergroups: myGroup it would produce:

class GroupedMembers

demonstrates member groups

myGroup

void in_mygroup_one(int myParameter)

A function.

void in_mygroup_two(int myParameter)

Another function.

Public Functions

void not_in_mygroup(int myParameter)

This one is not in myGroup.

Members-only

This will only show the members of a class, and not the class name, child classes or structs, or any information about the class.

.. doxygenclass:: ClassTest
   :project: class
   :members:
   :members-only:

It produces this output:

void function(int myParameter)

non-namespaced class function

More details in the header file.

More documentation in the impl file

void anotherFunction()

non-namespaced class other function

More documentation in the impl file

virtual void publicFunction() const = 0

namespaced class function

Without :members-only: it would produce:

class ClassTest

class outside of namespace

Public Functions

void function(int myParameter)

non-namespaced class function

More details in the header file.

More documentation in the impl file

void anotherFunction()

non-namespaced class other function

More documentation in the impl file

virtual void publicFunction() const = 0

namespaced class function

class PublicClass

A public class.

struct PublicStruct

A public struct.

class UndocumentedPublicClass

struct UndocumentedPublicStruct

Note

The members will be shown at the indentation normally reserver for class definitions. To prevent this, you may want to indent the block by indenting the .. doxygenclass directive.

Note

In the readthedocs theme, the members will show up in the color scheme of the class definitions. If you would like them rendered as the other members, indent like above, create a _static/css/custom.css file containing

/* render as functions not classes when indented (for :members-only:) */
html.writer-html4 .rst-content blockquote dl:not(.field-list)>dt,
html.writer-html5 .rst-content blockquote dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple)>dt {
  margin-bottom: 6px;
  border: none;
  border-left: 3px solid #ccc;
  background: #f0f0f0;
  color: #555;
}

and add the following to your conf.py

html_static_path = ['_static']

html_css_files = ['css/custom.css']

Outline Example

This displays only the names of the class members and not their documentation. The :members: and :private-members: options determine which members are displayed.

.. doxygenclass:: Nutshell
   :project: nutshell
   :members:
   :outline:

It produces this output:

class Nutshell

Public Types

enum Tool

Values:

enumerator kHammer

enumerator kNutCrackers

enumerator kNinjaThrowingStars

Public Functions

Nutshell()

~Nutshell()

void crack(Tool tool)

bool isCracked()

Qt Signals & Slots Example

Doxygen is aware of Qt Signals and Slots and so Breathe can pick them up and display them in the output. They are displayed in appropriate Signals, Public Slots, Protected Slots and Private Slots sections.

.. doxygenclass:: QtSignalSlotExample
   :project: qtsignalsandslots
   :members:

Produces the following output:

class QtSignalSlotExample : public QObject

Public Functions

inline void workingFunction(int iShownParameter)

Parameters:

iShownParameter – This is shown in declaration

Public Slots

inline void workingSlot(int iShown)

Parameters:

iShown – This is in function declaration

Signals

void workingSignal(int iShown)

Parameters:

iShown – This is in function declaration

Failing Example

This intentionally fails:

.. doxygenclass:: made_up_class
   :project: class
   :members:

It produces the following warning message:

Warning

doxygenclass: Cannot find class “made_up_class” in doxygen xml output for project “class” from directory: ../../examples/doxygen/class/xml/