Re: [Boost-docs] The beauty of LATEX

Subject: Re: [Boost-docs] The beauty of LATEX
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2011-10-18 11:37:06

> -----Original Message-----
> From: boost-docs-bounces_at_[hidden] [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of
> Matias Capeletto
> Sent: Tuesday, October 18, 2011 11:40 AM
> To: Discussion of Boost Documentation
> Subject: Re: [Boost-docs] The beauty of LATEX
> 
> On Tue, Oct 18, 2011 at 11:35 AM, Paul A. Bristow <pbristow_at_[hidden]> wrote:
> > But surely documenting the classes, member functions and functions API
> > is *part* of the task we are discussing?
> >
> > So I really, really do want to see *a* way of helping authors to
> > provide that information.  The Doxygen C++ code comments  /pre /post
> > /param /tparam /returns provide it :  "source coupled documentation" as Rene Rivera dubs it.
> >
> > I'm adamant that this requires a tool that 'understands' C++
> > (Gcc/Clang?) : that's all that many libraries are using Doxygen for.
> 
> The problem is that when you try to document generic C++ libraries, it is really difficult to
obtain the right
> information to make a useful reference for the user with automated tools. For example, you can get
> several free functions that are just there to gain performance (think of sort) and should be
documented as
> only one...  the concepts are the important bit here, and we still do not have them as part of the
language.
> Or you can have big templates machinery with ton of classes that serves as the guts of the lib. In
a lot of
> modern C++ libs, much of the code, classes, functions, are implementation details and the real
public API is
> quite buried and not easily obtained by the use of Doxygen like tools. When I tried to use it for
Bimap, the
> resulting documentation was only useful as a navigation aid for someone that wants to know how the
lib
> is implemented. And that was after a lot of manual work, making some parts of the codes invisible
to it
> using macros, and adding \code comments to directly replace some parts to help it.

I agree that it isn't easy to provide what the user wants without the 'But I can't see the woods for
the trees' syndrome.

But Doxygen does provide quite a lot control though input files and the various MACROs controlling
what is included, or not.

Explaining the often crucial template parameters was made impossible by the failure to pass through
\tparam comments, but Steven has kindly fixed this very recently, so finally it does allow the
author to explain what the template parameters can be and what they do.

Ticket URL: <https://svn.boost.org/trac/boost/ticket/5874#comment:1>

I would add that the C++ Reference Section is a *reference* : there must always be text, tutorial
and example sections too.

(We need not worry about document length much either - we are not wasting paper - so, for me,
*completeness* is a virtue).

(A " navigation aid for someone that wants to know how the lib  is implemented" sounds rather useful
for anyone taking over maintenance of the a library ;-)

> Maybe in the future, our language, augmented with real concepts will be more treatable.

OK - but concepts are now here yet - and we will still need a tool to process them automatically.
Surely they will only contain the same underlying information that Doxygen comments \pre \post
\return \param \tparam contain?

Paul

PS Just to give a concrete example of a reference section, I attach a snip of a newly generated item
from a reference section by a GSoC 2011 project's docs Checks C++ Reference Section.  You will see
the (rather terse) info passed through (as well as the synopsis).

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