Re: [boost] Doxygen documentation was Re: [review] Review of Outcome (starts Fri-19-May)

Subject: Re: [boost] Doxygen documentation was Re: [review] Review of Outcome (starts Fri-19-May)
From: Vinnie Falco (vinnie.falco_at_[hidden])
Date: 2017-05-27 17:51:57

On Sat, May 27, 2017 at 9:09 AM, Robert Ramey via Boost
<boost_at_[hidden]> wrote:
> 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.