-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Paul A. Bristow 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 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 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_numeric... and a PDF version at https://dl.dropboxusercontent.com/u/43940943/safe_numerics/libs/safe_numeric... Another version for authors/developers/maintainer with more detail, rebuilt by an addition in the jamfile doxygen:paramENABLED_SECTIONS=DETAIL https://dl.dropboxusercontent.com/u/43940943/safe_numerics/libs/html/index.h... (see, for example, Class template safe_range_base at https://dl.dropboxusercontent.com/u/43940943/safe_numerics/libs/safe_numeric... 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 +44 1539 561830 07714330204 pbristow@hetp.u-net.com