Subject: Re: [boost] Improving Documentation
From: Robert Ramey (ramey_at_[hidden])
Date: 2013-10-11 12:51:01
"Edward Diener" <eldiener_at_[hidden]> wrote in message
> On 10/11/2013 4:52 AM, Paul A. Bristow wrote:
>>> -----Original Message-----
>>> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Robert
>>> Sent: Friday, October 11, 2013 3:11 AM
>>> To: boost_at_[hidden]
>>> 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
>> *These descriptions are the key things that are missing for most Boost
>> 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
>> (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.
> Unsubscribe & other changes: