I generally believe that comments for users should not be inline in the code, as doxygen comments or anything like that. It should be a separate document, in prose form. As a user of the library, I don t need to, or want to, know what each parameter for a function means. Hopefully, that s obvious. I need to know what the function does. And I need to know why it does it and when to call it. And I need to know what pre- and postconditions apply. What assumptions does the function make when I call it, and what guarantees does it provide when it returns?

Library users don t need comments, they need documentation. Describe how the library is structured and how it works and how to use it, and do so outside the code, in an actual text document.

Of course, the code may still contain comments directed at maintainers, explaining why the implementation looks the way it does, or how it works if it s not obvious. But the documentation that the library user needs should not be in the code.

I think the best approach is to use Doxygen for header files to describe (to the users) how to use each class/method and to use comments within the .cpp files to describe the implementation details.

Well done, Doxygen commenting can be very useful both when reading code and when reading generated HTML. All the difficulty lies in Well done.

My approach is as following:

• For users of library, I put Doxygen comments in header files for explaining what is the purpose of that function and how to use it by detailing all arguments, return values and possible side effects. I try to format it such that generated documentation is a reference manual.

• For maintainers, I put basic (not Doxygen) comments in implementation files whenever self-commenting code is not enough.

Moreover, I write a special introductory file (apart from the code) in Doxygen format for explaining to new users of libray how to use the various features of the library, in the form of a user s guide which points to details of reference manual. This intro appears as the front page of the Doxygen generated documentation.

Doxygen allows the creation of two versions of the documentation (one for users and one for "internal use") through the internal command and the INTERNAL_DOCS option. It is also possible to have a finer grained control with conditional sections (see the if command and the ENABLED_SECTIONS option.)

As others have already noted, it is also useful to provide users (and also maintainers sometimes) something at a higher level than strictly code comments. Doxygen can also be used for that, with the mainpage, page, [sub[sub]]section and par commands

I recommend you to take a look at this paper: http://www.literateprogramming.com/knuthweb.pdf

I normally applied those ideas to my projects (using Doxygen). It also helps in keeping the doc up to date because it is not necessary to leave the IDE, so one can make annotations while coding and, later on, revise the final pdf document to see what needs to be updated or more detailed.

In my experience, Doxygen requires some work so that the pdf look nice, the graphs and pics in place, etc. but once you find your ways and learn the limitations of the tool, it gets the job done quite well.

My suggestion, besides what Kyle Lutz and Eric Malefant have already said, is to put long explanations about related classes in its own file (I use a header file for that) and add references to other parts using Doxygen tags. You only need to include those headers in the Doxygen configuration file (using pattern matching). This avoids cluttering your headers too much.

There is no quick easy answer, good documentation is hard.

I personally feel a layered model is best.

• high level docs in prose. Pictures and videos are very appropriate.
• reference level docs should Doxygen (well done doxygen, not just off hand comments).
• maintainer docs should not show up in the reference docs, but they could still be doxygen as pointed out by by Éric.

I really like the documentation style used in RakNet. The author uses extensive Doxygen comments and provides a generated reference manual. He also provides some plain html tutorials. Best of all he supplies video walk-throughs of some of the more complicated features.

Another good example is SFML. The quality isn t as good as RakNet but it s still very good. He provides a good overview page in the doxygen generated documentation. There are a few plain html tutorials and a plain html Features/Overview page.

I prefer these styles as Doxygen generated documentation is generally too low level when I m just starting out, but perfectly concise once I m in the groove.