Doxygen comments on declarations or on definitions?

Question

Just started using Doxygen for documenting my code here and can't decide where to put them.

At first look it seems better to put them in the declaration files as it is there where you actually declare what you receive, what you are going to return and stuff like that, apart from that things like data members that are only in the declaration files can obviously only documented there.

But often I find handier to comment methods in the implementation files as they are more accessible to me and the declaration file doesn't get cluttered with dozens of lines of comments making it harder to find what you look for when developing.

What is your experience with that?

Answer 1

IMHO, for interfaces, libraries, components its much better to add comments in the .h file. so that the .h gets distributed. Plus if you put comments in .h file, it will be shown in the Visual Studio, when you hover over a function call, as a tooltip.

Answer 2

I like to put them in the declaration: I usually look on a .h to know how to call a function, not in the implementation. Furthermore, if you distribute your code, people will have access to the header but not to the implementation.

Of course you could comment in both, but I think it's a bad idea as you would have to maintain it coherent ;)

Answer 3

I've seen projects that put all their documentation at the start of the implementation file, which is probably the worst you can do, as anyone reading the source and wanting explanation has to go look it up in hundreds of lines of ducumentation. Or go to the website or whatever.

Declaration is probably the best place.

Answer 4

You may want to check out these related questions:

• C/C++ Header file documentation
• Using Doxygen with C, do you comment the function prototype or the definition? Or both?
• How to be able to extract comments from inside a function in doxygen?

Answer 5

I prefer to keep the interface as clean as possible. The interface should explain itself ...
If prefer to put the documentation in the implementation file.

Answer 6

We prefer them as close to the implementation as possible. The rationale for this being that it increases the probability that the code and documentation stays in sync.

Answer 7

Comments with declaration.

I've personally used both styles. I've actually used a third where the documentation was split: @brief and @param in the header and all the rest in the source file, very bazaar. Currently, I prefer to put all Doxygen comments with the declaration and think I'll stick with that preference. I keep finding more reasons to keep doing it this way.

Doxygen with declaration favors users of the library. Where Doxygen with definition favors maintainers/enhancements. In my experience there are far more users of a library than there are maintainers.

I always treat my code as a library for other users. The old adage that a year from now you will be the other user is very true. While I am writing the class and I need quick reference of a class's interface, it's definition is plenty good enough. When I'm in that mode having the Doxygen comments in the header is just distracting. However, other-users/me-in-a-year will find the declaration to be insufficient to answer their questions. So they'll have to find the definition as well to get at the rest of the comments.

Answer 8

I work with Xcode these days and found out the following:

1.0 Scenario: Comments in declaration and definition = Doxygen puts both into the documentation.

2.0 Scenario: Comment in declaration or definition = Doxygen puts it into the documentation.

3.0 Scenario: Class comes with and interface/protocol that yields the comments in .h 3.1. Scenario: Comments only come from the interface declaration. = Doxygen puts the comments to the documentation.

3.2. Scenario: New comments are added to the implementation of the interface = Doxygen substitutes the interface comments with the implementation comments. The implementation comments have precedence.

3.3. Scenario: You add the declaration of the interface methods to your .h and put new comments = Doxygen substitutes the interface comments with the declaration comments of your class. The declaration comments have precedence.

3.4. Scenario: You add the declaration of the interface methods to your .h and put new in your declaration and definition. = Doxygen puts both into the documentation.

Now I ask myself if one would put all derived methods into my own declaration file like described in scenario 3.x. I more and more tend to put the comments into the definition file since all the magic happens there. By this I also would never miss a method to be documentated.