Subject: Re: [boost] Improving Documentation
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2013-11-19 10:55:04
Premature send - please ignore but watch this space for full message soon.
> -----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
> 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!
> In a sense the documentation for the user is trivial - once you have seem the examples, the rest
> docs is unlikely to be read. But the devil is in the details - they involve much meta-programming
> made my brain hurt.
> So there are two (unusually distinct) requirements for documentation - user, and
> 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
> header files.
> * Not GIT file layout compatible.
> 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/maintainer that also documents all the namespace detail sections. The later is much longer
> * 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 can
> 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
> 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
> 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
> (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
> '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.
> this information can easily be provided as a plain comment, for example: //! @b return number of
> type T.
> Concepts are a similar limitation, (until concepts are part of the C++ language). The Boost.GIL
> 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
> It is certainly true that the resulting documentation is much larger than one can produce manually
> read right through will appear highly repetitive. But disk space is no longer an issue and I
> completeness is valuable - it does not matter that the same information is in two places because
> makes is more likely that the reader will find it. For the author, much of the tedious part of
> comments can be reduced by copy and paste of 'boilerplates of comments'. For the reader, the key
> hyperlinking: the very many hyperlinks mean that the reader will never see the pages he is not
> in, but will always have the full information on the pages he does land on. The indexes mean that
> reader can approach from a subject term, a function, class or MACRO name, or a filename.