Re: [Boost-docs] question about using Doxygen

Subject: Re: [Boost-docs] question about using Doxygen
From: Edward Diener (eldiener_at_[hidden])
Date: 2011-06-20 23:59:36

On 6/20/2011 7:19 PM, Robert Ramey wrote:
> https://svn.boost.org/trac/boost/wiki/Guidelines/DoxygenGuidelines
>
> contains this text
>
> Documenting the Reference section following the C++ standard style
> Doxygen provides a certain number of tags that allows to generate a clean
> documentation, but it would be great if all the Boost libraries document its
> Reference section following the C++ standard style.

What is the "C++ standard style" ?

>
> which I would certainly like to do.  Looking at the Doxygen documentation
> it's not immediatly obvious whether or not Doxygen is useful for this task.

Doxygen can generate reference documentation for class templates, among 
other C++ constructs. I believe it has some problems with full and 
partial specializations.

It is up to the programmer to create the documentation as he wants it.

> It seems we have a few alternatives:
>
> a) use HTML directly - simple but tedious
> b) use BoostBook - complex but tedious
> c) quickbook - simple - but ... frustratnig? or not? - I'm just a little
> wary of a tool which does "too much"

Quickbook is so much easier than anything else that it should be a 
no-brainer to choose.

>
> Is DOxygen useful for generating reference documenation for template meta
> programming libraries? Or is it something that "can be made to work" which
> is a whole different thing than "just works".  Any one care to share their
> advice on the simplest way to get generate documentation for a library?

Use quickbook and doxygen. Look at any number of library documentation 
for how to setup the doc bjam file ( you can see my own libraries, VMD 
and TTI in the sandbox ).

Doxygen is simply a means to document C++ constructs via a short 
description and a long description, either being optional. With either, 
but especially with the latter, you can create completely free-form 
documentation, although doxygen also allows constructs in your doc which 
it understands.