Directives#

Most C constructs are available as an autodoc style directive.

Do to the fact that autodoc directives are set up into a global namespace and not in domain specific namespace. The directives used for auto documenting C constructs will have a c moniker in their names.

Keeping consistent with autodoc, the term member is used generically to refer to any sub construct of another C construct. For example in this documentation any usage a C function may be referred to as a member of a C module.

Common Options#

:noindex:#

By default the documentation instances are added to the index. To prevent an instance from being added to the index provide this option.

.. autocmodule:: filename#

Create documentation for filename. The filename is relative to c_autodoc_roots. This directive can be used for both C source files as well as C header files.

The contents of the first documentation comment will be utilized as the documentation for filename.

:members:#

Specify which members to recursively document.

This option has 4 states:

  • Omitted will result in the members entry of autodoc_default_options being used. If members is omitted from autodoc_default_options then no members will be automatically documented.

  • Specified as :no-members:, no members will be automatically documented.

  • Specified with no arguments, :members:, then all supported C constructs at the file level will be recursively documented.

  • Specified with a comma separated list of names, :members: function_a, struct_b, only the file members specified will be recursively documented.

:private-members:#

Specify if private members are to be documented. Since C doesn’t actually have a true idea of public and private, the following rules are used to determine these characteristics.

Members are public if:

  • They are in a header file, ends in .h. By nature header files are meant to be included in other files, thus anything declared there is deemed public.

  • They can be visible outside of the compilation unit. These are things the linker can get access to. Mainly this means functions and variables that are not static.

Just as for the standard autodoc options, one can use the negated form of :no-private-members: to selectively turn off this option on a per module basis.

:undoc-members:#

Specify if undocumented members are to show in the documentation. This option is off by default.

Just as for the standard autodoc options, one can use the negated form of :no-undoc-members: to selectively turn off this option when it has been enabled in autodoc_default_options.

.. autocfunction:: filename::function#

Document the function function from file filename.

The documentation will first attempt to utilize the output provided by clang. Clang can parse Doxygen style markup. So if the function parameter documentation or the function return value documentation is seen in the clang parsing, then the parsed clang documentation will be used. Otherwise the raw function comment block will be utilized.

.. autocmacro:: filename::some_define#

Document a C macro. Both macro constants as well as function like macros.

.. autoctype:: filename::typedef#

Document a typedef

.. autocenum:: filename::enum_name#

Document a enum

:members:#

Specify which members to recursively document.

This option has 4 states:

  • Omitted will result in the members entry of autodoc_default_options being used. If members is omitted from autodoc_default_options then no members will be automatically documented.

  • Specified as :no-members:, no members will be automatically documented.

  • Specified with no arguments, :members:, then all enumerator constants will be documented.

  • Specified with a comma separated list of names, :members: field_a, field_b, only the items specified will be recursively documented.

.. autocenumerator:: filename::enum_name.enumerator#

Document a enumerator. One of the constant values of an enum.

.. autocstruct:: filename::struct_name#

Document a struct

:members:#

Specify which members to recursively document.

This option has 4 states:

  • Omitted will result in the members entry of autodoc_default_options being used. If members is omitted from autodoc_default_options then no members will be automatically documented.

  • Specified as :no-members:, no members will be automatically documented.

  • Specified with no arguments, :members:, then all fields will be recursively documented.

  • Specified with a comma separated list of names, :members: field_a, field_b, only the items specified will be recursively documented.

.. autocunion:: filename::union_name#

Document a union

:members:#

Specify which members to recursively document.

This option has 4 states:

  • Omitted will result in the members entry of autodoc_default_options being used. If members is omitted from autodoc_default_options then no members will be automatically documented.

  • Specified as :no-members:, no members will be automatically documented.

  • Specified with no arguments, :members:, then all fields will be recursively documented.

  • Specified with a comma separated list of names, :members: field_a, field_b, only the items specified will be recursively documented.

.. autocdata:: filename::variable#

Document a file level variable.

.. autocmember:: filename::struct.field#

Document the specified field of a struct or union.

Note

This is one of the overloaded uses of the term member. This name was used to keep consistent with the member wording of the C domain.