[Please do not mail me a copy of your followup]
boost@lists.boost.org spake the secret code
- Everything is written in Quickbook - It is a true rewrite, not an edit of existing docs
So you do not see aplace for any of an existing pages in your new documentation? What about examples and existing tutorials? Do you cover all the components of Boost.Test?
I wrote all new tutorials, examples, user guide, etc. Over 4 years ago I posted this on boost-users when I wrote a series of tutorials on Boost.Test for my blog: "I don't know exactly what it is about the documentation, but its difficult for me to find stuff in there quickly. The easier it is to get started with a library, the more people use it. I don't know why, but Boost.Test feels hard to get started. Once I got it figured out, I decided that some tutorials would help others." This situation hadn't changed at all in 4 years, so I just decided to fix it by writing new documentation.
- Some Quickbook annotations are added to header files to briefly summarize the major classes/functions that a user of Boost.Test is likely to care about: test_unit, test_case, test_suite, master_test_suite_t, test_observer, unit_test_log_t, unit_test_log_formatter, init_unit_test_func, unit_test_main.
Why does this need to be part of source code?
This is how quickbook keeps documentation and header files synchronized.
- 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.
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. -- "The Direct3D Graphics Pipeline" free book http://tinyurl.com/d3d-pipeline The Computer Graphics Museum http://computergraphicsmuseum.org The Terminals Wiki http://terminals.classiccmp.org Legalize Adulthood! (my blog) http://legalizeadulthood.wordpress.com