Re: [boost] Improving Documentation

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

Sorry :-(

Premature send - please ignore but watch this space for full message soon.

Paul

> -----Original Message-----
> From: Paul A. Bristow [mailto:pbristow_at_[hidden]]
> 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 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/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 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.
> 
> 
> 
> 
> 
> 
>