On 3/17/2011 10:10 AM, Paul A. Bristow wrote:
-----Original Message----- From: boost-users-bounces@lists.boost.org [mailto:boost-users- bounces@lists.boost.org] On Behalf Of John Maddock Sent: Thursday, March 17, 2011 11:25 AM To: boost-users@lists.boost.org Subject: Re: [Boost-users] [Review] Boost.Type Traits Extension by FredericBron
* I note that is does not use an automated system like Doxygen of producing the reference information.
I would like to see the whole library Doxygen fully commented (ask if you think I can help) - replacing much of the current reference text.
Personally I wouldn't, sorry, but I'm still not completely sold on Doxygen :-(
Well I agree that it isn't the perfect tool.
(Doxygen gets confused with C++ and it's picky about linking comments to classes etc).
As a user I find the current 'hand-written' alternatives deeply unsatisfactory.
The bald synopsis just isn't good enough for the user.
The synopsis just gives the class and function name and parameters types.
But the user also needs to know what the parameters do, what the class or function does, what preconditions, what post conditions, what side effects, the "here be dragons" warnings, how to use it, examples ...
Most of this information *has* to be hand-written - whether in plain text, or in comments of some sort.
And it should all be in one place, not scattered.
Only the Quickbook-Doxygen reference section seems to do this - *provided the actual code is fully commented*.
I use doxygen, but there is nothing keeping a quickbook author from writing hand-written comments instead. So it is incorrect to claim that "Only the Quickbook-Doxygen reference section seems to do this". Like you I still think doxygen is good enough since the long form of doxygen comments can be anything. But some people do find doxygen difficult, and I can understand that. I still think that good docs go beyond just using doxygen and need explanations in topics and good organization, and sometimes this is lacking in Boost docs. But John Maddock's documentation is always first-rate.