With doxygen, when should the comments be placed before the entity, and when after?

Question

Here are two styles of commenting on an entity (e.g. in a C/C++ like language).

Style 1:

// This is a comment
// about foo
int foo;

// This is a comment
// about bar
int bar;

Style 2:

int foo;
    // This is a comment
    // about foo

int bar;
    // This is a comment
    // about bar

I know that, usually, when writing a doxygen comment, it's typically appears before the documented entity, e.g.:

/// This is a doxygen comment
/// about foo
int foo;

/// This is a doxygen comment
/// about bar
int bar;

Is that always the case, or can I place it after the entity, as in the second commenting-style above?

Answer 1

Yes, you can place your doxygen comments after the commented-on item, but in that case you have to add a special marking to the comment. This is explained in the Doxygen documentation:

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:

int var; /*!< Detailed description after the member */

This block can be used to put a Qt style detailed documentation block after a member. Other ways to do the same are: ...

int var; ///< Detailed description after the member
         ///<