Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2013-11-19 10:18:14

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Paul A. Bristow
> Sent: Wednesday, October 16, 2013 10:17 AM
> To: boost_at_[hidden]
> Subject: Re: [boost] Improving Documentation
> 
> > -----Original Message-----
> > From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Robert
> > Ramey
> > Sent: Tuesday, October 15, 2013 5:42 PM
> > To: boost_at_[hidden]
> > Subject: Re: [boost] Improving Documentation
> >
> > >> Another test-case example?
> >
> > Here's my test case example:
> >
> > http://htmlpreview.github.io/?https://raw.github.com/robertramey/safe_
> > numerics/master/safe_numeri
> > cs/doc/html/index.html
> 
> OK - I'll rise to this challenge to convert to Quickbook and prepare C++ reference section using
Doxygen
> comments (as best I can, not being the library author).
> 
> But not for a week or too - the cement dust level is too high ;-)

The dust level in my house has fallen below danger levels and so I have been able to spend some time
working on Robert Ramey's challenge to document his proposed Boost Library version of Safe Integer.

Like the previous challenge, it is a bit of a googly - it has about one class and 3 functions!

In a sense the documentation for the user is trivial - once you have seem the examples, the rest of
the docs is unlikely to be read.  But the devil is in the details - they involve much
meta-programming and will made my brain hurt.

So there are two (unusually distinct) requirements for documentation - user, and author/maintainer.
(Is a reason we have unmaintained libraries that the detailed documentation is poor?)

Before you inspect the demonstration, some caveats:

*  This is a not a Boost library, nor even a draft library (Robert is already on version 3!).
*  I am not the author and I don't fully understand it.
*  There are bound to be mistakes.
*  It is not fully documented - this would be a waste of effort as it is under development.
*  Some comments are obviously contrived,  just to demonstrate some features.
*  For my convenience, transferred all the code to the boost-sandbox file format, and changed all
the header files.
*  Not GIT file layout compatible.

What I want to show is how I think it is the *combination* of Quickbook, Doxygen comments providing
for the C++ References section, and AutoIndex that is key to providing what all users want.

I have produced two versions (automatically generated) which are for users, and another for
author/maintainer  that also documents all the namespace detail sections. The later is much longer
of course.

* Changed Boostbook.css to user different syntax colors (my personal choice - but I like it much
better).

* In the C++ Reference section only, always underline links to make them stand out better.  I think
it is much clearer when navigating around this section.

Some of the desirable features that I hope this demonstrates:

* Nice formatting with Quickbook.

* Preparation of both html and pdf versions.  The pdf version is a single standalone file that can
be used offline.  All the PDF document can easily be searched for any text using the Find function.

*  Code snippets and sample output - that have actually compiled and run (no typos!).

* Links to the actual code examples.  "You can see the full example code at example2.cpp"

* Quickbook within code examples - making it easy to understand what the example demonstrates, and
also include output.

* Syntax colored code.

*  Lots of hyperlinking (but everyone does/should do that!).

*  Automatic legal stuff - copyright and license info on every page.

*  Links to Trac tickets (well, of course, actually there are none yet ;-)

* Using Doxygen to generate Standalone Doxygen documention - a quick firststep to confirm that
everything has been commented syntactically correctly and completely (you can get warnings for any
undocumented items).  (This avoids annoying errors showing up later - and inscrutably - at the
slower-to-rebuild Quickbook stage).

*  Using Quickbook with Doxygen to prepare a Boost.Safe Numerics C++ Reference section.

* Using Doxygen comments to record meaning of function parameters, template parameters

* Using Doxygen \cond DETAIL... \endcond to Exclude items that are not relevant to users  (but allow
creating a separate set of docs with more to be visible to developers and maintainers where other
stuff, for example in namespace detail, are also documented).

* Since the Quickbook/Doxygen C++ Reference section is centered on the .hpp include files, also use
AutoIndex so that all the functions, class, and macros are listed alphabetically.  This means that
if the function names is known, from the text,  

*  Provide the compile-time 'return' from MPL using a Doxygen comment like "return maximum bits in
Numeric types T and U"

* Provide an index of other text terms (not just automatic functions, classes...) provided by the
author (I'ver added a few ramdomish index terms into the file safe_numerics.idx).

One of the limitations noted (and given as a reason for not using Doxygen) was that although Doxygen
'knows' about all the C++ language features, and has a \return comment item for this purpose,
Doxygen does not recognise the compile-time computed 'return' of 'result' from a MPL template
function.  But this information can easily be provided as a plain comment, for example: //! @b
return number of bits in type T.

Concepts are a similar limitation, (until concepts are part of the C++ language).   The Boost.GIL
library pioneers a method of automatically providing concept using BOOST.Concept, and this could be
used here.  For now, I have used a simpler link to the concept  like
http://www.sgi.com/tech/stl/RandomAccessContainer.html.

It is certainly true that the resulting documentation is much larger than one can produce manually
and if read right through will appear highly repetitive.  But disk space is no longer an issue and I
believe that completeness is valuable - it does not matter that the same information is in two
places because it makes is more likely that the reader will find it.  For the author, much of the
tedious part of writing the comments can be reduced by copy and paste of 'boilerplates of comments'.
For the reader, the key is hyperlinking:  the very many hyperlinks mean that the reader will never
see the pages he is not interested in, but will always have the full information on the pages he
does land on.  The indexes mean that the reader can approach from a subject term, a function, class
or MACRO name, or a filename.