Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2013-10-11 04:52:23

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Robert Ramey
> 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 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.

Paul

(The process of providing hyperlinking to docs move from sandbox to release is byzantine but this
should get improved when we get GITized).

---
Paul A. Bristow,
Prizet Farmhouse, Kendal LA8 8AB  UK
[phone]  07714330204
pbristow_at_[hidden]