Re: [boost] Improving Documentation

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

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Paul A. Bristow
> Sent: Tuesday, November 19, 2013 3:18 PM
> 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/saf
> > > e_
> > > 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 now 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!

(but a lot of brain-twisting MPL meta-template wizardry under the hood!)

In a sense the documentation the user needs is trivial - once you have seem the examples, the rest
of the docs is unlikely to be read. 

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

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/Developer/Maintainer  that also documents all the namespace detail sections. The latter is
much longer of course.

I've made two cosmetic changes:

* 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 -
useful if the author hasn't added your search term to the index.

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

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

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

* Syntax colored C++ code.

*  Lots of hyperlinking (but everyone does/should do that!).  Doxygen makes it easy to hyper-hyper-
link.

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

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

* Using Doxygen to generate Standalone Doxygen documentation - a quick first step 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 name is known, from the text,  you can jump straight to it.

*  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've 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 pioneered 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 might produce by hand.
If read right through it will appear highly repetitive - but I don't think that what users do - they
jump about.  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 Doxygen 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.

Before you inspect the demonstration, some caveats:

*  This is a not a Boost library, nor even a draft library (Robert is already wizarding on version
3!).
*  I am not the author and I don't fully understand it.
*  There are many omissions and 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 - yet.

You can see the results of my efforts at

https://dl.dropboxusercontent.com/u/43940943/safe_numerics/libs/safe_numerics/doc/html/index.html

and a PDF version at

https://dl.dropboxusercontent.com/u/43940943/safe_numerics/libs/safe_numerics.pdf

Another version for authors/developers/maintainer with more detail, rebuilt by an addition in the
jamfile 

      <doxygen:param>ENABLED_SECTIONS=DETAIL

https://dl.dropboxusercontent.com/u/43940943/safe_numerics/libs/html/index.html

(see, for example, Class template safe_range_base at

https://dl.dropboxusercontent.com/u/43940943/safe_numerics/libs/safe_numerics/doc/html/header/boost/
safe_numerics/safe_range_hpp.html

for more than you probably want to know ;-)

Discussion and feedback welcome of course.

Paul

---
Paul A. Bristow,
Prizet Farmhouse, Kendal LA8 8AB  UK
[phone]  07714330204
pbristow_at_[hidden]