On 10/11/2013 4:52 AM, Paul A. Bristow wrote:
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Robert Ramey Sent: Friday, October 11, 2013 3:11 AM To: boost@lists.boost.org Subject: Re: [boost] Improving Documentation
Andrew Hundt wrote:
I have to say Boost's documentation is generally excellent.
Thanks for indulging me - I trying hard not to rant.
I'll try hard too ;-)
We *still* don't have a single example of using *ALL* the tools we already have to prepare documentation. All the examples of deficiencies you note *can* be met - except the docs being small files and quick to build (but size doesn't matter provided one can navigate around well).
Quickbook provides a nice markup system for plain text - and it provides the hooks and eyes to get to code snippets and Doxygen comments.
Doxygen (as used in this toolset) provides a way to add code comments to all the code elements - functions, data, macros etc. Using it with Quickbook is only a way to link these comments to the C++ reference section so that you can click on any function name and find its description, preconditions, post conditions, parameter and template parameters descriptions.
*These descriptions are the key things that are missing for most Boost documentation*.
The usefulness of the docs is mainly determined by the work that goes into these descriptions.
Autoindex provides an index - automatically for all the above C++ elements, and manually given some work. All the index items are hyperlinks. Boost.Math shows this in action - though it needs more manually added index terms - more work!
PDF single file that can be printed like a book (as well as HTML).
Many libraries use some tools, but none use *ALL* of them.
I've recently re-factored the circular_buffer library using all these tools.
(But I'm not the author so I can't claim to make as good a job as someone who really understands the code could do - it's only a refactoring).
Maybe you'd comment again when you've seen this example.
As you say the tools are there. But I do not think the difficulty of some of the docs are a matter of tools. I believe it is a matter of the structure of the documentation for some of the libraries and also that programmers typically are much more focused on correct code than they are on really good documentation. Some Boost documentation is really excellent while some other Boost documentation assumes a great deal on the part of the programmer using the library and explains much less of the general concepts of the libary than it could. I am one of those who believe that a thorough overview of a library is very important, even more important than examples, but then I am probably deficient myself in providing examples for libraries I write.