Re: [boost] Boost.Test documentation update; alpha release

From: Paul A Bristow (pbristow_at_[hidden])
Date: 2007-08-13 12:38:01

>-----Original Message-----
>From: boost-bounces_at_[hidden] 
>[mailto:boost-bounces_at_[hidden]] On Behalf Of Gennadiy Rozental
>Sent: 12 August 2007 10:27
>To: boost_at_[hidden]
>Cc: boost-users_at_[hidden]; boost-docs_at_[hidden]
>Subject: [boost] Boost.Test documentation update; alpha release
>
>Hi,
>
> I've finally been able to produce alpha release of completely 
>reworked 
>BoostBook based documentation for Boost.Test library. It's 
>still not ready 
>for release and I expect significant changes in both L&F (once I apply 
>latest IBD based style) and content (some articles still 
>missing). But it's 
>in a shape close to what I would like it to be.
>
>  I would really appreciate any comments to both content (language 
>including) and style. I realize it might not be small 
>undertaking so if you 
>have time for just part of it, please post comments as well.
>
>The release is available here:
>
>patmedia.net/~rogeeff/html/index.html
>
>in patmedia.net/~rogeeff/src you can find sources.

1  First line 1 space indent is a bit odd - not enough to be a real indent.
And anyway I don't think indents help!  so I'd go for now indents.

2  No icons for navigation - but perhaps they will appear when in the right place.

3  You must explain what a UTF is before using the acronym.

4  No Last revised date.  This should be added to the TOC automatically?

5  The minimal testing facility supplies it's own ... should its ( it isn't it is, is it!)

6  The code block backgroun in is too dark (and the code font a bit small too).

7  I would break up the code and 'inline' the comments.  It makes it much more difficult to read having to go down to (1), and then
(2) ...  But I'm sure you're tired now ;-)  But for future reference...  (using the code blocks syntax for the code)  For example:

// seven ways to detect and report the same error:

  BOOST_CHECK( add( 2,2 ) == 4 ); // continues on error

displays an error message (by default on std::cout) that includes the expression that failed, the source file name, and the source
file line number. It also increments an error count. At program termination, the error count will be displayed automatically by the
Unit Test Framework.

  BOOST_REQUIRE( add( 2,2 ) == 4 ); // throws on error

similar to approach #1, except that after displaying the error, an exception is thrown, to be caught by the Unit Test Framework.
This approach is suitable when writing a explicit test program, and the error would be so severe as to make further testing
impractical. BOOST_REQUIRE differs from the C++ Standard Library's assert() macro in that it is always generated, and channels error
detection into the uniform Unit Test Framework reporting procedure.

...

Since this section is what most people want to start with, it would be worth splitting it up?

8  Mention pre-built libraries - bjam never works first time :-(

9  Admonishment Important duplicates on Standalone library compilation.

10  It would help if you said in the Including the UTF directly into your test module section that recompilation will *slow down*
your 'compile, run, crash' cycle ;-)
 
11 It didn't quickly see the thing I need most, most often - a list of the macros

BOOST_CHECK ...

Eventually I found 'The UTF testing tools reference' but only by accident !

12 You could help the ignorant (eg me) with a link

[@http://en.wikipedia.org/wiki/Buridan's_ass Buridan's donkey]

13  MS .net specific "jump through these errors using usual keyboard shortcuts/mouse clicks you use for compilation error annalists"
Spelling 
mistake 'analysis'

14  You've shown using a Post-Build step, but say Use Custom build step.

I find Thorsten's Custom build step method convenient too with just

"$(TargetDir)\$(TargetName).exe" 

and c:\autorun as the mythical filename.

This re-runs, even if not rebuilt.

But perhaps there are advantages to the post-build method too?

I find that these are rather important convenience features allowing a rapid run/test cycle.

15 Test progress display is blank.  TODO?

16 I don't like the output in white on black, but taste in 'color' is *very* subjective - and some people have no taste at all ;-)

17  YOC pages has a number of footnotes/callouts [1]  [2] ... but they appear to be orphans - but contain interesting info and the
links are missing. 

18 Finally IMO it badly needs an index - but we have yet to devise a good method of automatically indexing Quickbook docs.

Overall looks and works MUCH nicer  - well worth the pain;-)

HTH

Paul

---
Paul A Bristow
Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB
[phone] & SMS, Mobile [phone] & SMS
pbristow_at_[hidden]