From: Paul Baxter (pauljbaxter_at_[hidden])
Date: 2007-08-13 16:03:22
>> The release is available here:
>> in patmedia.net/~rogeeff/src you can find sources.
Thanks for devoting effort to updating the docs of this important library..
My first impressions as a likely new user of Boost Test is, not very good,
I don't find a clear statement of intent or capabilities beyond a one liner.
It goes straight into the heart of things next without answering my basic
question, 'what can it do for me?'.
When I get into the various sections, it is difficult for me to grade
information as critically important, useful user background, an
implementation quirk or gotcha, a limitation etc.
Perhaps its more about the documentation needing some more consistent
*organisation* of the information rather than the content itself.
I don't want to be overly critical of your work in progress, so what sort of
comments are you looking for?
I started off going through page by page, but it became apparent early on
that my comments might be getting counter-productive. I've left them below
but don't take them to heart, please.
As a reasonable focus for people without much time, perhaps they could take
a look at say 'execution monitor'.
Look at the compilation page for Execution monitor for instance.
There are only a few sentences but I'm left reeling.
That 'one source file', is it a .hpp or a .cpp or both (broken link refers
to a .ipp, text refers to a .hpp and later a .cpp)?
Your text: 'In some cases you may want to include the source file along with
header file into your sources. But be aware that ...this file will bring a
lot of dependencies.'
- well should I use it or not? Is there a lightweight alternative if I
just want to catch some types of errors? If its good enough to be used as
the basis for core components in boost.Test, why should I be concerned about
all the dependencies it brings in?
Next page: Execution monitor user guide
Lots of really good information but its style makes it hard work to wade
Perhaps make it more explicit:
What does the function do
What are its parameters
What are its quirks and limitations
Tips on how to use it
All questions are answered there somewhere, but its quite difficult for me
to take it all in because of the form in which its presented.
Having read the much better introduction to the next section 'Program
execution monitor' I ask myself why I just spent time with 'execution
Here are a few other ad-hoc comments
1) Front page:
- Email address at top of page has an unfortunate mis-spell of the word
also since your account is boost-test@ etc you might want to remove the
confusing use of hypen to also delimit other words e.g. -at- -dot- etc.
- Footnotes at the bottom of the page do not seem appropriate to this page
'The Program Execution Monitor is also useful in some production (non-test)
environments' doesn't really help. What is it; is it different from the
'matched set of components ...controlling their runtime execution' you refer
to in the previous sentence?
Perhaps a sentence or two to distinguish the capabilities for the four parts
referred to on the contents page as I to IV?
'Boost.Test internal tests have been run (and work) under numerous
Perhaps reword. e.g.
'Boost.Test supports all main Boost compilers and platforms. Confirmation of
its status on core and additional platforms/compilers can be seen by viewing
Boost.Test's own internal regression test results <here> and <here>'
Link to release notes?
General comment. This page is perhaps an ideal one to briefly describe a
little more about the capabilities first and an outline of components within
Boost Test. Perhaps a picture capturing the essence?
At present as a new reader I still know very little about the scope of this
library. (I know you have the material later but an overview here wouldn't
I think in terms of my unit tests, organisation of those tests into suites,
how info is reported/displayed, what helper functions/capabilities would be
good (compile time asserts, error trapping/reporting). I want to know that
this library addresses my problems (and I know it does and gives me so much
Not sure I'd put FAQ and open issues as sub-sections under introduction ....
3) FAQs - agree largely with Peter Foley's comments. At least in the FAQ,
could you put 'Unit Test Framework (UTF)' at least once in this page so that
people who are really new, instantly understand without a glossary at hand.
With a new library I usually visit - introduction/overview then 'guide for
the impatient/getting started if available and FAQ before I wade in any
These should be free from too many three letter abbreviations (TLAs) if
4) Open Issues
5) Execution Monitor
Not sure this is best placed as the first section after introduction. It
appears from what I read up to this point that it is a core low-level
building block and at this point I'm thinking, well is this an
implementation detail or an advanced feature or something I should care
about right now. It hides lots of mess, but should I, as a user, care about
Probably yes, but I'm not sure.
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk