"Paul Baxter" <pauljbaxter@hotmail.com> wrote in message news:BAY144-DAV173B3621EBC31CAA3BEF9AB5DC0@phx.gbl...
The release is available here:
patmedia.net/~rogeeff/html/index.html
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'm afraid.
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?'.
Yes. For a long time I am looking for someone to write some introductory paragraphs for the library. I am not that good with these things. Any volunteers please speak up.
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.
Can you give an example annotated with how would you prefer it to look like?
Perhaps its more about the documentation needing some more consistent *organization* of the information rather than the content itself.
What wrong with current organization?
--------------------------------------- As a reasonable focus for people without much time, perhaps they could take a look at say 'execution monitor'.
execution monitor is not probably the best component to start with.
Look at the compilation page for Execution monitor for instance. http://patmedia.net/~rogeeff/html/execution-monitor/compilation.html
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)?
Exact wording: "The Execution Monitor is implemented in two modules: one header file and one source file." difference between .ipp and .cpp is technical and I plan to explain it in "fine print"
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?
Should or should you use it depends on you need. These section describe how you can use it (if you decided to)
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?
I am not sure what you are trying to say, but the statement is just trying to explain the consequences of including the execution_monitor.ipp into your source file.
Next page: Execution monitor user guide http://patmedia.net/~rogeeff/html/execution-monitor/user-guide.html
Lots of really good information but its style makes it hard work to wade through.
Perhaps make it more explicit:
What does the function do What are its parameters
This is in reference section
What are its quirks and limitations Tips on how to use it Advanced features
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.
I am not sure how to fix above, but accidentally I found that execution_monitor::execute usage description is completely outdated and incorrect. This one is fixed ;))
Having read the much better introduction to the next section 'Program execution monitor' I ask myself why I just spent time with 'execution monitor'
Ummm. These are two different beasts.
------------------- 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 'account' 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.
Fixed
- Footnotes at the bottom of the page do not seem appropriate to this page
Yeah this is bug in BoostBook
2) Introduction:
First paragraph: '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?
Yeah. Intro is desperately needs couple paragraph update.
Portability para: 'Boost.Test internal tests have been run (and work) under numerous compilers....' 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>'
Ok. Updated.
Link to release notes?
Where?
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?
Which page?
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 hurt).
I think in terms of my unit tests, organization 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 more).
Can you provide specific paragraphs and where you want them?
Not sure I'd put FAQ and open issues as sub-sections under introduction ....
See below [...]
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 it? Probably yes, but I'm not sure.
I guess I need big clear disclaimer somewhere at the very beginning, but the Boost.Test documentation is not intended to be read from top to bottom, like a book. I had a hard time ordering different parts of docs. Should execution Monitor goes first or last? On one hand it's implementation details for majority of the users, but on the other hand it referenced in UTF - so it should be explained before - and in general is standalone Boost.Test component. Where should "open issues", "portability", "release notes" sections go: at the beginning or at the end. At the end I decided to follow regular site order where these items are accessible from top level or in this case at the beginning. I am open to suggestions though. Regards, Gennadiy