Re: [Boost-docs] Sphinx integration

Subject: Re: [Boost-docs] Sphinx integration
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2011-10-03 16:15:01

> -----Original Message-----
> From: boost-docs-bounces_at_[hidden] [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of
> Dave Abrahams
> Sent: Monday, October 03, 2011 3:05 PM
> To: boost-docs_at_[hidden]
> Subject: Re: [Boost-docs] Sphinx integration
> 
> >>>> And lets not forget that some of us really like quickbook ;-)

+1

> >>> Although may intention was to discuss the workflow of documenting
> >>> Boost, I think I have identified what is the biggest pain to me:
> >>> Doxygen integration in BoostBook.
> >>>
> >>> Doxygen is widely used C++ code documenting tool.
> >>> Fortunately or unfortunately, it is also used by many Boost authors.
> >>>
> >>> Doxygen does not support many of the terms/concepts/elements used
> >>> across Boost libraries. It is also becasue it is almost impossible
> >>> to document them well at source code levels.

But Doxygen *does support* as comments

\param and \tparam  - telling what parameters do, and/or, for example, if they must be default
constructible or bidirectional iteratable.

\pre  - pre-conditions  

\post - results apart from

\returns  what the result it, and constraints.

\remarks - could be used for terms etc.  

\see  - see also - references to toher stuff.

\warning  - if 'bad' parameter values will be caught, thrown, or cause trouble...

which can be very conveniently used to document concepts and other features.

As a reader of Boost stuff, I find the lack of this information in many libraries quite annoying,
both reading the source code, and especially when reading the user documentation.  

Using Doxygen properly and fully, I feel that Boost documentation could be much improved.

What is wrong is the common delusion that you just chuck your C++ code into Doxygen it magically
does the whole job :  it doesn't - it is a tool for *helping you to document your source code*. 

You have to do the work - and experience has shown that it is much easier done when you first write
the code!

The Quickbook tool chain just organises the presentation as a C++ reference section within your
textual documentation.

Paul

PS There are some buglets in the implementation of some of these items at present, but I trust that
we will get them sorted soon.
Meanwhile you can still get the benefit reading the source code, and you can also use Doxygen's
'Standalone' presentation, liked by some and loathed by others.