doxygen - documentation after members (///<) does not work

Question

Heya,

I'm trying to document my C code with doxygen, however using the "documentation after members" style doesn't seem to work for me. The doxygen documentation says:

Putting documentation after members

If you want to document the members of a file, struct, union, class, or enum, it is sometimes desired to place the documentation block after the member instead of before. For this purpose you have to put an additional < marker in the comment block. Note that this also works for the parameters of a function.

Here are some examples:

[...]

Most often one only wants to put a brief description after a member. This is done as follows:
int var; //!< Brief description after the member
or
int var; ///< Brief description after the member

Minmal source example:

/** @file  test.c */

void foo(void) {
    uint8_t bar; ///< Some random variable
}

My Doxyfile is pasted here.

Instead of getting some description of the variable in the documentation, I get this:

2.1.1 Function Documentation

2.1.1.1 void foo ( void )

< Some random variable

Anyone happens to have an idea why?

Zeta Zeta · Accepted Answer · 2013-04-09T18:55:11

The member documentation syntax is meant for, well, members.

Members are values in a class or struct (or however your language might call it). Local variables are not members and thus not covered by doxygen.

The reason for this is that usually the members of a class are critical for its state, so you desperately want to document those, as derived classes might use protected members for example.

Functions on the other hand don't need such documentation for their local variables. After all, those are local. A function should thereby be defined by its total observable behaviour, as the local variables aren't important for the user:

struct object_type{
    struct object_state_type state; ///< the object's state
};

void bad_documentation(void) {
    uint8_t bar; ///< Some random variable
}

/// \brief Initializes the global state of the omnipotence object.
void good_documentation(void) {
    uint8_t bar;

    /** \remark The object needs to be initialized exactly once,
    *           otherwise we have some problems.
    */
    assert(some_global_var != 0);

    /** One can check `some_global_var` whether the global object 
    *   has been initialized
    */
    some_global_var = 1;

    /// Finally, the object going to be initialized.
    impl_obj_state_init(&the_global_object.state);
}

doxygen - documentation after members (///<) does not work

Putting documentation after members

2.1.1 Function Documentation

2.1.1.1 void foo ( void )

2 Answers