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
> time working on Robert Ramey's challenge to document his proposed Boost Library version of Safe
> 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
> docs is unlikely to be read.
> So there are two (unusually distinct) requirements for documentation - user, and
> (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
> 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
> 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
> * 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
> used offline. All the PDF document can easily be searched for any text using the Find function -
> 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
> * 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
> 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
> creating a separate set of docs with more to be visible to developers and maintainers where other
> for example in namespace detail, are also documented).
> * Since the Quickbook/Doxygen C++ Reference section is centered on the .hpp include files, also
> *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
> (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
> 'knows' about all the C++ language features, and has a \return comment item for this purpose,
> 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
> bits in type T.
> Concepts are a similar limitation, (until concepts are part of the C++ language). The Boost.GIL
> 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
> It is certainly true that the resulting documentation is much larger than one might produce by
> read right through it will appear highly repetitive - but I don't think that what users do - they
> Disk space is no longer an issue and I believe that completeness is valuable - it does not matter
> same information is in two places because it makes is more likely that the reader will find it.
> 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
> pages he is not interested in, but will always have the full information on the pages he does land
> The indexes mean that the reader can approach from a subject term, a function, class or MACRO
> 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
> * 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
> header files.
> * Not GIT file layout compatible - yet.
> You can see the results of my efforts at
> and a PDF version at
> Another version for authors/developers/maintainer with more detail, rebuilt by an addition in the
> (see, for example, Class template safe_range_base at
> for more than you probably want to know ;-)
> Discussion and feedback welcome of course.
> Paul A. Bristow,
> Prizet Farmhouse, Kendal LA8 8AB UK
> +44 1539 561830 07714330204
This archive was generated by hypermail 2.1.7 : 2017-11-11 08:50:41 UTC