Richard
This situation hadn't changed at all in 4 years, so I just decided to fix it by writing new documentation.
Trunk version of docs did improve on that in my opinion, but this is besides the point.
- Some Quickbook annotations are added to header files to briefly Why does this need to be part of source code?
This is how quickbook keeps documentation and header files synchronized.
So quickbook is like doxigen? Does it parse C++ sources?
- Boost.Test code in trunk is used as "the truth" for understanding how something actually works
So, you reverse engeneer all new features, right?
It's not clear what is a new feature and what is simply an undocumented internal mechanism. So no, I documented the stuff that everyone needs and the stuff that people appear to be using in boost by grepping trunk. This is already a little bit more than what the old documentation covered.
What is that you cover that existing pages do not, for example? Did you base your decision on what is needed on content of Boost own unit tests? The problem with this is that these obviosly does not include any of new features and these are indeed completely missing from docs. Even worse they use number of old interfaces, which are now deprecated. Most important example is testing tools: BOOST_CHECK_EQUAL, BOOST_CHECK_CLOSE - all these tools are now deprecated and I wouldn't spend any time detailing their use. New testing tools is the one to use from now on and these are the one that needs to be coverred.
Would you be interested in my input? We can take this offline.
I will post for wider review once I finish my first pass, which is probably going to happen soon. Right now, I'm just using a few people for feedback as I go.
You are free to do what you think best, but I would imagine that if you want something which reflects real state of Boost.Test (in other words something, which we can actually use for release), we probably need to talk sooner rather than later. Regards, Gennadiy