Re: [boost] [docs][crc] Did I do new documentation correctly?

Subject: Re: [boost] [docs][crc] Did I do new documentation correctly?
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2012-01-08 09:52:02

> -----Original Message-----
> From: boost-bounces_at_[hidden] [mailto:boost-bounces_at_[hidden]] On Behalf Of Daryle
> Walker
> Sent: Saturday, January 07, 2012 3:57 AM
> To: boost_at_[hidden]
> Subject: [boost] [docs][crc] Did I do new documentation correctly?
> 
> 
> I completely redid the documentation for Boost.CRC in changeset [76335].  It uses Doxygen and
> Quickbook. 

Looks rather nice (and quite complete) - at a quick glance.

> Other concerns:
> 1. The quickbook/doxygen system doesn't seem to handle "\todo" constructs correctly.

This is a TODO ;-)

> 2. Is there a way to #define various common macros, like BOOST_STATIC_CONSTANT, so they get
> expanded correctly in Doxygen? 

You can find various examples of people dealing this problem - I've collected some examples at

https://svn.boost.org/svn/boost/sandbox/tools/quick_auto_dox_index/libs/quick_auto_dox_index/doc/jam
file.v2

> Is there a "Doxyfile," or can the needed Doxygen parameters be tweaked in the Jamfile.v2?

Yes - tweak via your jamfile.v2.  The above file is over-documented to document the many
possibilities.

You might like to enforce documentation of all functions - and then get a report of any missing
their documentation in a warnings.log file?

> 3. I guessed that the next release will be "1.49.0", is that right?

I believe so, but time is short?

> 4. Content-wise, did I miss anything?

History of trac items dealt with?  mods etc?

None of the macros are Doxygen documented.  This might be useful for some users?

How about an index?

This can be produced automatically using John Maddock's autoindex.

http://www.boost.org/doc/libs/1_48_0/tools/auto_index/doc/html/index.html

You will need to put some work into an crc.idx file for the users to get most out of it, but even
just feeding everything through will be better than nothing - will index all functions and macros.

For an example to follow, you might find Pierre Talbot's Checks Google Summer of Code project
helpful.  His documentation uses all the tools quite fully, including an index.  See his checks.idx
file for an example - you can probably use some of his index entries directly 

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

Keep up the good work ;-)

Paul

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