Re: [boost] [units] problems

Subject: Re: [boost] [units] problems
From: Robert Ramey (ramey_at_[hidden])
Date: 2013-09-16 14:32:48

Paul A. Bristow wrote:
> I've had good results using Boost.Units - after much puzzlement and
> frustration.
>
> I think there are several problems (at least).
>
> 1  Units are complicated - very, very complicated.  Even if we could
> ditch Imperial and US units, the fundamental weight in kg makes
> trouble.  There are many conversions that are essential for the thing
> to be useful.

agreed - that's why we need the library.

> 2 Implementing them in C++ using templates to avoid any runtime cost
> proved to need concerted efforts from the best brains we have.

speaking for myself, I'm using the best brain I have.

> The whole idea is secure conversion, so explicitness is vital - but
> annoying and puzzling.

I understand this - it's a key point and a very subtle one

> 3  The examples are quite good - but pack a lot (probably too much)
> into a small space.

agreed.

> 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.

> 5  After the years of struggle to get it working, I can appreciate
> that the authors are very tired. And there are other juicy challenges

lol - you're preaching to the choir.  I doubt anyone appreciates
this issue more than I do.

> I believe that someone else should write a bigger set of smaller
> examples (also drawing on the many replies to cries of help) and use
> these as Quickbook snippets.  With better documentation and examples,
> I think this brilliant package might get the full use it deserves.

my  2 cents here.

a) I would like to see reference documentation which looks like other
reference documents for templated libraries - ie built around type
constraints (aka "concepts").

b) After a) I would like to see a tutorial which incrementally builds
up the knowledge from the simplest most widely used cases to
the more subtle and less widely used ones.

I know a lot about this subject because I learned the hard way. I had
a lot off difficulty documenting the serialization library.  I didn't get
it right the first time and received an incredible amount of criticism
for this.  Finally I figured it all out and the library was much the better
for it.  Now I go and look at other libraries and I get the feeling that
they really need improvement along the same lines.  The units is sort
of special in that it's more difficult than other libraries and it's
potential utility is huge.  I really believe that this library (units) 
should
be as widely used as the serialization library is now.  But I see no
hope of that happening unless this issue is addressed.

> But I don't think that I am volunteering!

lol - me neither - but I'm happy to tell other people how to do it!

Robert Ramey