-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Robert Ramey Sent: Monday, September 16, 2013 7:33 PM To: boost@lists.boost.org Subject: Re: [boost] [units] problems
4 The C++ Reference documentation (as you observe) lacks the vital info about what all the template and other parameters do (pretty much Concepts by another name).
totally agree. Its more than that, writing this documenation and the concepts classes clarifies
the library
user interface and likely feeds back into the design/implementation of the library itself.
This needs a lot of Doxygen comments and is a massive and tedious task - especially as many of these are not trivial and need to be quite detailed with notes and links to examples.
I've got mixed feelings about Doxygen in addressing this problem. I did do a little bit of investigation on this (see www.blincubator.com) and reached the tentative conclusion that Doxygen wasn't suitable. The basic problem is that documention a templated library is a different animal than documention non- templated classes. Another problem with Doxygen is that often times the documentation ends up just parroting the code rather than providing the extra insight. Long and short of it - I'm not convinced that Doxygen can do this.
You are right in that Garbage in-Garbage out applies - as ever. Doxygen *comments* only provide a way to supply the words to describe what a parameter is for - and how you use it - and as much extra info as you like. The Doxygen comments 'syntax' is pretty simple : //! \brief A base unit represents a specific measure of a dimension. //! \tparam System System of a unit, absolute unit or quantity, for example `mks_system`. but you can easily provide much more here, for example, a `see also` link \see base_unit_info to get the name of the unit as a string or an abbreviation. a sample of usage ... \code base_unit_info<meter>.name() // The full name of the unit (returns BaseUnit::name() by default) \endcode Many links are automatically provided so you can jump about easily. You already see this in action - but there is little text to help you when you get somewhere. (And don't confuse documentation which has just be fed into Doxygen 'standalone' with using Doxygen comments to provide the information to appear in the Quickbook C++ Reference section. Using Doxygen comments is only a convenient way of getting text into the C++ Reference). Doxygen comments *can* do the job. But it's a lot of hard work - like everything to make it easy for the user :-) Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com