Subject: Re: [boost] [test] still broken in release
From: Richard (legalize+jeeves_at_[hidden])
Date: 2013-08-09 09:29:18
[Please do not mail me a copy of your followup]
boost_at_[hidden] 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
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>
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk