Re: [Boost-docs] question about using Doxygen

Subject: Re: [Boost-docs] question about using Doxygen
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2011-06-21 16:38:13

 -----Original Message-----
> From: boost-docs-bounces_at_[hidden] [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of
> Robert Ramey
> Sent: Tuesday, June 21, 2011 6:07 PM
> To: boost-docs_at_[hidden]
> Subject: Re: [Boost-docs] question about using Doxygen
 
> > What is the "C++ standard style" ?
> 
> I'm assuming that this means style similar to the SGI documentation for stl libraries.  I was sort
of
> expecting to find some sort of "form filling" approach or something "automatically" generated ala
> Doxygen.  It's interesting to me (but not surprising) that their is a wide difference of opinion
as to the
> utility of Doxygen in our context.  I'm quite intrigued by this.
> 
> My current (toy) project has not classes per se - it's all concepts a la fusion.  So I don't see a
good place
> where something like Doxygen fits in.  Unless ....
> 
> I've created Concepts using BoostConceptLibrary for all the concepts I use.  Now it's occuring to
me that
> perhaps Doxygen comments might best be applied to these concept checking classes.  They're
templates -
> but I don't see that this should be an insurmountable problem.

FWIW, I'd very strongly support improvement to the Boost docs by including the sort of information
that you describe in the SGI docs (and lots of others).

I believe that Doxygen is specifically designed to help.

http://www.stack.nl/~dimitri/doxygen/commands.html lists all the commands.

(not all are recognised by Boostbook - but I suspect more could be with a modest amount of work? The
really useful ones *are* supported.)

All files should have a "\\! \file" comment to ensure the current filename is taken.

(\author seems not necessary as we have a name of the copyright,  and \date doesn't add much for the
space it takes up).

\brief

and 

\detail should be provided for all files - so the poor readers have some clues what it is for!

\pre \post \param (for all of them) \return are the main ones, 

\see and \warning might be useful too?  (But not supported by BoostBook yet?)

But especially for your application ...

\tparam would also be useful for templated code (very popular with Boosters ;-)

Steven said on 2 Apr" I've just committed basic \tparam support to the trunk".

So use trunk version because it is what you really want :-)

Paul

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