Re: [boost] [test] still broken in release

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 <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>