[Boost-docs] FW: [boost] Improving Documentation

Subject: [Boost-docs] FW: [boost] Improving Documentation
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2013-11-20 12:08:38

Cross posted in case ...

> -----Original Message-----
> From: Paul A. Bristow [mailto:pbristow_at_[hidden]]
> Sent: Tuesday, November 19, 2013 4:59 PM
> To: 'boost_at_[hidden]'
> Subject: RE: [boost] Improving Documentation
> 
> > -----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/s
> > > > af
> > > > 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.ht
> ml
> 
> 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/b
> oost/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]