You must be logged in to post a comment.
Wow. Thanks for the review! And sorry for the long delay for my reply. I literally just saw this (it would be nice if somehow I would get an e-mail when people leave comments).
I have done a bit of work on the documentation since you left your comment last July. The whole doxygen pipeline is set up and all public classes/functions have doxygen comments (and some even have doxygen code samples which are compiled and tested automatically). I’d really appreciate you taking another look at the documentation and letting me know if I’ve fixed the issues you noted and also let me know what still needs improvement. I spent some time writing a design/rational section as well as including a FAQ page.
First of all I would like to congratulate you on being the first (other than myself) to use this site. I appreciate your doing this and hope you get valuable feed back.
Here’s my initial feed back from a quick review of the documentation and looking a bit at the code.
On the plus side
a) clearly you’ve put a huge effort into this.
b) presentation from quick book is neat and readable.
c) I very much like that you’ve supported Bjam as well as CMake. Since I wrote my critique of build systems on this site, I’ve had occasion to be become more familiar with CMake and my opinion on the matter has evolved. I will be updating my comments on this part of the site.
d) I believe that this is an extremely interesting area for a boost library. Your timing is excellent!
On the minus side
a) The documentation is way to little for a package of this scale. From looking at the comments on GitHub, I’m guessing that there is a bunch of DOxygen generated stuff which is still pending. It turns out that my opinion of DOxygen has also evolved now that I’ve become familiar with it. Still, I have a lot of concerns about the documentation of templates. I personally had a lot of problems with this when I wrote the documentation for the serialization library. Check my comments on the subject on this site. Also you might take a look at the safe_numerics sample library on this site to see how I think documentation of templates should be addressed.
b) Assuming the issues regarding the reference part of the documentation get addressed, there is still the most important part of the documentation to consider – the narrative. Consider adding the following sections to your documentation:
Introduction - what problem does the library solve
Motivation example #1
Motivating example #2
hy did we do it this way instead of that way
Why we can't do it the way someone else does it
References - pointers to relevent background material
Basically the documentation has to motivate potential reviewers to invest sufficient time to give the library the attention it deserves. So you have to make it as painless as possible to understand and use. It’s not there yet.
There are many examples – from great to awful – in the Boost Libraries and documention is almost always a complaint from reviewers and users.