-----Original Message----- From: Paul A. Bristow [mailto:pbristow@hetp.u-net.com] Sent: Tuesday, November 19, 2013 3:18 PM To: 'boost@lists.boost.org' Subject: RE: [boost] Improving Documentation
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Paul A. Bristow Sent: Wednesday, October 16, 2013 10:17 AM To: boost@lists.boost.org Subject: Re: [boost] Improving Documentation
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Robert Ramey Sent: Tuesday, October 15, 2013 5:42 PM To: boost@lists.boost.org 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
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 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
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
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
Sorry :-( Premature send - please ignore but watch this space for full message soon. Paul the providing think it is library the
reader can approach from a subject term, a function, class or MACRO name, or a filename.