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