Re: [Boost-docs] Sphinx integration

Subject: Re: [Boost-docs] Sphinx integration
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2011-10-06 06:24:00

> -----Original Message-----
> From: boost-docs-bounces_at_[hidden] [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of
> Dave Abrahams
> Sent: Wednesday, October 05, 2011 5:26 PM
> To: boost-docs_at_[hidden]
> Subject: Re: [Boost-docs] Sphinx integration
> 
> I'm not so sure.  The universe of design options is so vast that I think users need to be
presented with
> alternatives.  I find http://cpp-next.com far easier to read than most of the Boost pages, for
example.

I like that too, but I fear we are not discussing the most important thing.

This is focussing on style : I'm worrying about *detailed content* - and what is I believe is often
missing from many Boost docs.

For me, the really important issue problem is how and where to document what class, functions, etc
do, pre and post conditions, 'concepts' and results, returns and side effects, and what it does if
you provide bad input - throw or error code or?.

You can get off to a good start with good choices of names, but if you have function 'flip', then
somewhere you need to document "Swaps the byte order".  And there are all the other items as well.
"return result;"  doesn't help the user much!

*No automated tool is going to write all this for you*.

So we have two choices.

You provide separate text, perhaps in text and/or tables, separately.  But for any non-trivial
library, you need a tool to organise this, and this means some 'mark-up' system.  And keeping the
docs in step with the code is more difficult.

Or you put the documentation in with the C++ code as comments with some 'mark-up'.  This is all the
Doxygen conventions do - and they could be processes by other tools too, best of all by an add-in to
the compiler.  This clutters the code, but syntax color makes this a non-problem for me.  (You are
reading this in color and not B&W ;-)

I've only used Doxygen and I think it can be made to work well enough.

Are there other tools that could help us more?

Paul

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