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

Subject: Re: [boost] [test] still broken in release
From: Gennadiy Rozental (rogeeff_at_[hidden])
Date: 2013-08-09 15:01:51

Richard <legalize+jeeves <at> mail.xmission.com> writes:

> 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