Re: [boost] [units] problems

Subject: Re: [boost] [units] problems
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2013-09-16 14:24:56

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Robert Ramey
> Sent: Monday, September 16, 2013 7:33 PM
> To: boost_at_[hidden]
> 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
[phone]  07714330204
pbristow_at_[hidden]