Doxygen C++ conventions

Question

I'm at the beginning of a C++ project and I've been using Doxygen from the start.

I'd like to know how you use Doxygen in your project, i.e. I have several questions:

1. Where do you put your Doxygen comments? Header or sources?

I think that they should go to the header, because that's where I look to find out how to use methods. However, I like to omit actual parameter names in prototypes, so I can not use @param - or can I? How do you tackle this?

2. Do you document all methods?

I'm only documenting public methods so far, how do you do it? Do you document accessor methods and public variables?

3. Do you always fill out @param and @return?

Where I work (it's Javadoc, but it's the same issue), we have a convention to fill only actually needed properties, i.e. if the brief descriptions says "Returns xys if ...", we omit @return. If the parameter names are obvious, we omit them. I'm still not sure if I like that approach, how do you do it? So far, I've only filled out the brief and nothing else, but not all method prototypes are straightforward enough for that.

4. Which style do you use?

There are several styles in Doxygen: Javadoc (/** ... /), QT (/! ... */) and more. Purely out of interest: Which one do you use? I'm going with Javadoc style ATM because I'm used to it.

Answer 1

I can't answer 1, because I actually don't current remember where I tend to document in terms of header vs source. But as for the others:

2. Do you document all methods?

Almost completely yes. Every single method gets some form of documentation, unless it is instantly obvious from the variable/method name (and parameter names for methods) what it does in specifics. I tend to go by the rule of "If you can't work out the purpose of a method by it's name and parameter names, it needs a comment. If after commenting you still cannot work out the purpose of the method, re-write the comment. If you still cannot see very quickly the purpose of the method, or if the comment is 'too long' (where 'too long' is an arbitrary measurement >_>), then you need to re-write the method or split it up."

3. Do you always fill out @param and @return?

Yes. Even if it's blindingly obvious from reading the brief, or if the @return is an exact copy of sentence in the brief, I still fill them in. It can be very useful to have that sort of scan property for a method's documentation. "Oh, method X, I know what it does and why, but what exactly is its return value in X situation again?" *check the @return *.

4. Which style do you use?

Javadoc myself, although this is completely subjective. I use the Javadoc syntax because I spent a while writing in Java and got very used to that syntax. I also personally think it makes more sense than the others - I just don't like the QT syntax at all.

Answer 2

1. Where do you put your Doxygen comments? Header or sources?

Documentation goes in headers since this is where the interface is defined.

2. Do you document all methods?

For classes, I document all of the public and protected methods, I generally leave private methods alone.

3. Do you always fill out @param and @return?

I prefer the inline parameter documentation

/*!
 * \brief My great class.
 */
class Foo
{
public:
    /*!
     * \brief My great method.
     */
    void method(
        int parameter    //!< [in] parameter does something great
    );
};

to using \param since it results in duplication of the parameter name, and can easily get out of sync with the code when lazy developers forget to change the doxygen.

\return is omitted when there's a void return type. I always use \throw when the method can throw.

4. Which style do you use?

Does not matter as long as its consistent in the entire project.