Example C File

Below is an example of a auto documenting an entire C file. Click on any of the [source] links to jump to the location in the raw source file.

Begin Autodocumented C File

This is a file comment. The first comment in the file will be grabbed. Often times people put the copyright in these. If that is the case then you may want to utilize the pre processing hook, c-autodoc-pre-process.

One may notice that this comment block has a string of *** along the top and the bottom. For the file comment these will get stripped out, however for comments on other c constructs like macros, functions, etc. clang is often utilized and it does not understand this pattern, so the c-autodoc-pre-process hook may be something to use to sanitize these kind of comments.

MY_COOL_MACRO(_a, _b)

A function like macro

An attempt will be made to derive the arguments of the macro. It will probably work in most instances…

Function like macros can be documented with the :param: and :returns: fields. One could even utilize the napoleon extension to format something like:

Parameters:

• _a – The time of day as derived from the current temperature.

• _b – The place to be.

Returns:

The predicted value of stocks based on _a.

TOO_SIMPLE

A simple macro definition

struct a_struct_using_member_comments

Structures can be documented.

When the structure is anonymous and hidden inside a typedef, like this one, it will be documented using the typedefed name.

The members can be documented with individual comments, or they can use a members section. This example struct documents the members with individual comments.

float first_member

The first member of this specific structure using a trailing comment, notice the < after the comment start

int second_member

This member is documented with a comment proceeding the member.

typedef int a_typedef_type

A plain old typedef

enum anon_example_3051923531

Anonymous enums are supported, so that the enumerators can be documented.

Note

That one will not be able to autodoc the enum directly it will only be included by autodocing a module. Since it’s name will be built up dynamically

enumerator AN_ANONYMOUSE_1

The first enumerator from an anonymous enum.

enumerator AN_ANONYMOUSE_2

The second enumerator from an anonymous enum.

struct inline_struct_variable

Even structures defined in variables can be handled.

int a

float b

struct members_documented_with_napoleon

This example structure uses the Members: section and lets napoleon format the members.

int one

The first member of parent struct

struct two

This is a structure declared in the parent struct its children are documented below.

float nested_one

The nested member documentation

int nested_two

The second nested member documentation

float three

The third member of parent struct

int my_func(float hello, char what)

This is a function comment. The parameters from this are much easier to derive than those from a function like macro so they should always be correct.

Since the backend parser is clang and clang supports doxygen style comments One can document functions using normal doxygen style markup.

Parameters:

• hello: – The amount of hello appericiations seen so far.

• what: – The common reply character seen.

Returns:

The increase on hello’s in order to maintain politeness.

int napoleon_documented_function(int yes, int another_one)

One can also use Goolge style docstrings with napoleon for documenting functions.

Note

Functions do not support mixing doxygen style and napoleon style documentation.

Parameters:

• yes – A progressive rock band from the 70s.

• another_one – Yet one more parameter for this function.

Returns:

The square root of 4, always.

enum some_enum

If you want to document the enumerators with napoleon then you use the section title Enumerators:.

enumerator THE_FIRST_ENUM

Used for the first item

Documentation in a comment for THE_FIRST_ITEM. Note this is trailing, for some reason clang will apply leading comments to all the enumerators

enumerator THE_SECOND_ENUM

Second verse same as the first.

enumerator THE_THIRD_ENUM

Not once, note twice, but thrice.

enumerator THE_LAST_ENUM

Just to be sure.

int some_flag_variable

File level variables can also be documented