Re: [Boost-docs] Sphinx integration

Subject: Re: [Boost-docs] Sphinx integration
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2011-10-05 10:55:57

> -----Original Message-----
> From: boost-docs-bounces_at_[hidden] [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of
> Dave Abrahams
> Sent: Tuesday, October 04, 2011 11:35 PM
> To: boost-docs_at_[hidden]
> Subject: Re: [Boost-docs] Sphinx integration
> 
> > On 04/10/11 18:16, Dave Abrahams wrote:
> >> on Mon Oct 03 2011, "Paul A. Bristow" <pbristow-AT-hetp.u-net.com> wrote:
> >
> >>> 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!
> >>
> >> If that is indeed the case, Paul, someone (I'm lookin' at you) needs
> >> to write a guide to using Doxygen for Boost.  I would definitely try
> >> to use it next time if someone could show me how to make it really
> >> work for our docs.
> >
> > Paul listed very useful features and directives of Doxygen, but
> > without explanation how to use them to write rockstar documentation for Boost.

Ah well - as it happens - I have already put some effort into recording what I have learned so far
from those who know more about the toolchain that I do (and still including very many warts and
wrinkles, and woefully wonky bits),

http://svn.boost.org/svn/boost/sandbox/tools/quick_auto_dox_index/libs/quick_auto_dox_index/doc/quic
k_auto_dox_index.pdf

(you could also build the html version using the jamfile - but who wants to build docs?  Updating
SVN is a pain because file names keep changing).

and I've started on a template that other can used to get started quickly.

https://svn.boost.org/svn/boost/sandbox/guild/mylibrary/libs/mylibrary/doc/mylibrary.pdf

but did not appear to be used by anyone,  so I've taken to trying to lead by individual
encouragement.

To give the flavour of what you get, you might like to look at

1  My quick and rough translation of Beman's Endian docs into this format.

See

https://svn.boost.org/svn/boost/sandbox/endian_2/libs/endian/doc/html/index.html

or

https://svn.boost.org/svn/boost/sandbox/endian_2/libs/endian/doc/endian.pdf

If you look at the class template endian

https://svn.boost.org/svn/boost/sandbox//endian_2/libs/endian/doc/html/boost/endian/endian_endiannes
s_big___id303725.html

you can see the descriptions of endian functions, for example:

operator T() const;

Returns:  value of endian, the current value stored in *this, converted to value_type.

The ! after /* or // signals to Doxygen that it should associate the comment items with the C++
code.

//! \return value of @c endian, the current value stored in @c *this, converted to @c value_type.

Of course, many of these items are short, and perhaps trivial, but they can be longer if
appropriate.  At least you can be sure of completeness.

AND

2  The results of Pierre Talbot, the GSoC student that I mentored this summer (and put the hard word
on him to write the docs using these tools - including switching on a Doxygen switch that nags you
if you fail to document every class, function etc).

For his Quickbook toolchain generated docs see

https://svn.boost.org/svn/boost/sandbox/SOC/2011/checks/libs/checks/doc/html/index.html

or to see what I call the 'Standalone' Doxygen display is

http://svn.boost.org/svn/boost/sandbox/SOC/2011/checks/libs/checks/doc/doxygen/html/index.html

(In this case the Doxygen 'mainpage' only provides links to other source and documentation, and the
usual class, functions ...  Some people like this display - it shows inheritance etc structure well,
and is compact : others loath it.  But it does NOT (usually) include the 'text' that most people are
writing in Quickbook and similar markup tools.)

You can compare what you get by looking at the 'Checks Reference section' and the 'Class list' and
choosing a class to find what they might do for you.

(This is work still in progress - the sandbox docs do not correspond exactly to current C++ code,
but you can get the flavour).

/*!
    \brief Validate a sequence according to the isbn13_check_algorithm type.

    \pre check_seq is a valid range.
    \post No side effects.

    \tparam check_range is a valid range type.
    \param check_seq is the sequence of value to check.

    \throws std::invalid_argument if check_seq doesn't contain exactly EAN13_SIZE digits.

    \returns @c true if the check digit is correct, @c false otherwise.
*/
template <typename check_range>
bool check_isbn13 (const check_range& check_seq)
{
  return boost::checks::check_sequence<isbn13_check_algorithm, EAN13_SIZE> ( check_seq ) ;
}

Note the template parameters are described as well as parameters.

Other 'concepts' like Concepts that are not part of the C++ language could be accommodated by
convention using the \note or \remark comments?

Finally do not forget that you can get an *index* of all this, for zero or modest effort. How many
times have I forgotten what a Boost function or macro is called or does?  An index would have saved
so much Googling (and bad language and blood pressure elevation!)

Now I'm not pretending that all this comes for free - it does mean a lot more work for the author
(and it clutters the source code), but IMO the results are vastly more useful to the *user* and well
worth the effort.  Lots of recent authors are making the effort and I'd like to raise the bar if we
can.

Tell me what more I can do to help.

Paul

PS When I said a lot more work, you will note that I have not yet updated Boost.Math docs to fully
use Doxygen. (John groaned when I mentioned it!). But if I was starting now, I would definitely do
it.