On Sat, May 27, 2017 at 9:09 AM, Robert Ramey via Boost
I understand the appeal of Doxygen. ... BUT ... c) By providing a place to add a little narative to each method it gives the programmer the impression that he's documenting his library - which he is not actually doing. In most cases all he is doing is making the comments in the code visible through some browser. Nothing wrong with this, but he's not really adding anything that one couldn't gain from just browsing the source code.
Right. I'd like to make it clear to all readers of my posts which promote Doxygen and my docca library, that I am advocating for its usage specifically to build ONLY a "reference." That is, a synopsis of each public symbol (functions, classes, constants, etc...) exposed by the library, with appropriate helpful descriptions. Example: http://vinniefalco.github.io/beast/beast/ref/http__read_some/overload1.html Good documentation MUST include more than just this reference, it should also include the exposition that we have become accustomed to in Boost library documentation. An explanation of the audience, what problems the library solves, holistic tutorial on how to put things together to achieve a goal, and so forth. This of course will not be captured by Doxygen and instead should be developed as its own separate source code which is edited by hand much the way someone might write a novel. The approach used in docca and Beast is to incorporate this additional exposition not generated by doxygen as a set of ".qbk" files. The reference is then included as a pice of this larger work. To reiterate, Doxygen is a very useful piece (but not the only part) of a documentation tool chain in order to generate a reference from Javadoc comments attached to declarations in source code. It should be part of a larger work that includes the traditional exposition found in high quality documentation.