Boost logo

Boost :

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
<loom.20130808T054201-956_at_[hidden]> thusly:

>> - 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 <>
     The Computer Graphics Museum <>
         The Terminals Wiki <>
  Legalize Adulthood! (my blog) <>

Boost list run by bdawes at, gregod at, cpdaniel at, john at