----- Original Message -----

legalize+jeeves@mail.xmission.com (Richard) writes:

...

[Please do not mail me a copy of your followup]

Boost.Test documentation rewrite: http://user.xmission.com/~legalize/tmp/boost.test/libs/test/doc/html/

FWIW, I've been using this as my go-to Boost.Test documentation for some time now. It's a significant improvement on the existing docs.

+1, I've bookmarked it for a reference.

[Please do not mail me a copy of your followup] boost@lists.boost.org spake the secret code <009f01cf089c$3e4ae5d0$bae0b170$@hetp.u-net.com> thusly:

It could be AutoIndexed, but this may be less helpful than for other libraries, but at least a macros listing would be good?

Everything should be accessible at a glance from the main table of contents. Is there something missing from there?

PS But there are still updates in trunk/develop that are yet to be released?

Yes, there are a few minor things that I wrote up based on trunk that I have removed from this version. Then there a whole pile of changes that the maintainer has not documented and it is unclear which of these are really ready or not.

While things are in a state of major change, would not be a good time to try to get Boost.Test sorted out?

I'd rather document the current 1.55 release and move forward. It's already taken over 6 months to get to this point, I see no point in delaying any further. -- "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

Beman Dawes writes:

On Fri, Jan 3, 2014 at 12:13 PM, Richard wrote:

...

I'd rather document the current 1.55 release and move forward. It's already taken over 6 months to get to this point, I see no point in delaying any further.

With all reviews in favor and none against, it seems clear you should move forward with this.

I hoped I still have some say in this. I outlined my concerns in another post. I would prefer not to make any movement until we get to some consensus on these. Regards, Gennadiy

Beman Dawes writes:

On Thu, Jan 9, 2014 at 3:25 AM, Gennadiy Rozental

wrote:

...

Beman Dawes writes:

...

On Fri, Jan 3, 2014 at 12:13 PM, Richard wrote:

...

I'd rather document the current 1.55 release and move forward. It's already taken over 6 months to get to this point, I see no point in delaying any further.

With all reviews in favor and none against, it seems clear you should

move

...

forward with this.

I hoped I still have some say in this. I outlined my concerns in another post. I would prefer not to make any movement until we get to some consensus on these.

Gennadiy,

1) The library hasn't had much attention for several years, so I'm personally against further delay. While normally we wouldn't think of

going

forward with a major docs rewrite against the wishes of the library maintainer, you just haven't been responsive to documentation complaints for what seems like eons of time.

Boost.Test trunk has better improved documentation.

2) One of the objectives of modularizing boost was so that we could encourage wider participation, yet avoid giving boost-wide write authorization to new contributors. It seems to me the work Richard is doing is a very useful example of that.

I am all for working with Richard on new docs. I am just not sure this particular version worth time people will need to spent to get used to it. What Boost.Test really need is to document new release. And this is what we should be targeting. New features and new docs look and feel will make it all worth while. Gennadiy

Richard writes:

...

I am all for working with Richard on new docs. I am just not sure this particular version worth time people will need to spent to get used to

it.

...

What Boost.Test really need is to document new release. And this is what we should be targeting. New features and new docs look and feel will make it all worth while.

Again, I'm not sure why you didn't reply to my call for reviewers that I posted last May.

Again, becasue this was not I want us to spend time on.

You're saying I ignored you, but when I email you or post to the mailing list, you don't reply.

Show me a single post where you agree to work me on new documentation. All your post are about this is how my old docs should have looked liked. Whether or not I agree with this criticism is irrelevant and I do not have time to spend on useless bikering. I want us to do something productive instead.

I just don't find that you're being helpful while at the same time blaming me for not doing what you want.

Yes. I was not going to be helpful to do something which does not have much value in my opinion. You docs probably written better, with better english and some external prospective allowing you to better single out important parts. Yet you bound to be limited by expirience you have personally and my goal is to serve all users of the library equally, both new and old. I know the design of the library, it's pablic interfaces and how I would like it to grow. And in this unique moment I also know which parts of the library I want to deprecate and thus stop advertise them through documentation. If this is your final word, I will have no choice but to look for someone else to help me with this (or continue to procrastinate on best frasing as I did last half a year). What you want to do with this docs is up to you and rest of boost community. Regards Gennadiy

[Please do not mail me a copy of your followup] boost@lists.boost.org spake the secret code <561059F5-FA00-4F37-87AD-22C04C4C8DAC@comcast.net> thusly:

It sounds to me as if you both want useful documentation for Boost.Test, and have been willing to cooperate. Gennadiy has expressed ongoing interest in collaborating on documentation for the new APIs. Richard, if you're still interested in helping, can you agree to help on the new version? If not, Gennadiy's idea to link to your docs for the old, soon to be deprecated, interface seems appropriate.

I was told that the documentation can be updated at any time and isn't tied to a particular release, unlike features. I don't understand why we can't update the documentation *now*, make things better *now*, and get on with incremental improvements after that. The documentation for this library has a long history of not being updated promptly and new features lagging for a long time. Why can't we simply make things better immediately and then look at anything that is new? Why do we have to wait? Forcing a delay in adopting what has already been done in order to document new features doesn't seem to benefit anyone. -- "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

On Jan 21, 2014, at 3:40 AM, Gennadiy Rozental wrote:

Richard writes:

...

I was told that the documentation can be updated at any time and isn't tied to a particular release, unlike features.

Usually this would be the case, but what you propose in major overhaul of the content and structure. This is something which is bound to be disruptive to existing users (even if your version is better in some aspects). The will be people who will find something wrong with almost anything.

Your concern regarding disruption is partly valid, but if Richard's version is released now and you later link to it as the documentation of deprecated features if and when the new APIs are reviewed and accepted, it won't be so disruptive. As for your concern about docs not pleasing everyone, while true it doesn't seem significant considering the overwhelming support for Richard's rewrite.

...

I don't understand why we can't update the documentation *now*, make things better *now*, and get on with incremental improvements after that.

Because what I have in mind is not incremental improvement over what you propose.

That's a valid argument, but it doesn't mean releasing Richard's docs would be problematic.

...

Why can't we simply make things better immediately and then look at anything that is new?

Because I am not convinced it is better form all points of view. In fact I know it is worse from the standpoint of being boost.test library documentation: it's incomplete. And I already listed other reasons.

It's clear that many Boost developers like the new documentation and don't find it lacking. Perhaps a compromise is possible, however. Could Richard's version be released as the main documentation, with a link to your current docs in a section with an explanation that the linked docs discuss less commonly used parts of the library?

...

Why do we have to wait?

If anything needs to be released today, we can upgrade release branch to the trunk version of boost.test docs. This version addresses most of outstanding issues with errors in content.

That ignores the overwhelming preference for Richard's version.

...

Forcing a delay in adopting what has already been done in order to document new features doesn't seem to benefit anyone.

Forcing users to adopt to one version only to be replaced by something else soon does not look beneficial as well.

I've addressed that here and in my reply to Richard. I don't think it's the issue you make it out to be. ___ Rob (Sent from my portable computation engine)

On Jan 20, 2014, at 2:48 PM, legalize+jeeves@mail.xmission.com (Richard) wrote:

boost@lists.boost.org spake the secret code <561059F5-FA00-4F37-87AD-22C04C4C8DAC@comcast.net> thusly:

...

It sounds to me as if you both want useful documentation for Boost.Test, and have been willing to cooperate. Gennadiy has expressed ongoing interest in collaborating on documentation for the new APIs. Richard, if you're still interested in helping, can you agree to help on the new version? If not, Gennadiy's idea to link to your docs for the old, soon to be deprecated, interface seems appropriate.

I was told that the documentation can be updated at any time and isn't tied to a particular release, unlike features.

I don't know who told you that or why, but Boost documentation is release specific. How can it be otherwise? Each release can have different functionality. If you meant that it's possible to replace the latest releases docs at any time, I think that's possible.

I don't understand why we can't update the documentation *now*, make things better *now*, and get on with incremental improvements after that.

I didn't mean to suggest that yours couldn't be pushed as the latest, but that it would become the old, deprecated features documentation once the new API was documented, reviewed, and accepted.

The documentation for this library has a long history of not being updated promptly and new features lagging for a long time.

I would certainly require a very long time to create and update docs in French, though I know a little of that language, so I can understand Gennadiy's slowness. I don't recall how proactive he was in seeking help.

Why can't we simply make things better immediately and then look at anything that is new?

It's fair to say that many are inclined in your favor. Gennadiy has said your docs don't document the new state of the library, so yours will be short lived if the new state is adopted fairly soon. OTOH, if the new APIs are rejected, releasing the new version will be delayed or never occur making your version long(er) lived. Given the idea of linking to your version as documentation of the deprecated APIs when (if) the new version is released, your docs will be useful for some time either way, and that bolsters your case. Still, the question remains whether you're willing to document the new APIs, too. ___ Rob (Sent from my portable computation engine)

[Please do not mail me a copy of your followup] boost@lists.boost.org spake the secret code <86ha8wnwir.fsf@doc.ic.ac.uk> thusly:

Other than adding documentation for BOOST_TEST, BOOST_TEST_REQUIRE and BOOST_TEST_WARN, and trivial changes to tutorials to favour those macros, everything Richard has written would remain the same.

Agreed, as far as the "new API" is concerned. There are some command-line arguments (one or two, I think) in trunk that are not in release and they have not been documented. -- "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

On 1/12/2014 10:25 AM, Paul A. Bristow wrote:

...

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Gennadiy Rozental Sent: Saturday, January 11, 2014 3:17 AM To: boost@lists.boost.org Subject: Re: [boost] Call for Review: Boost.Test documentation rewrite

...

...

...

I am all for working with Richard on new docs.

You do not convince me, both from my experience trying to work on documentation improvement with you, and the list interchanges with Richard and others.

His documentation is not perfect, but it is far, far better IMO, and it's what I use for everyday work, and I'm sure I am not the only one doing this. So I'd like to see Richard's documentation of the current release Boost.Test adopted now.

Most important, his documentation is *maintainable* by anyone with a plain text editor and Boost tools. I see this as a key *requirement*.

...

I am just not sure this particular version worth time people will need to spent to get

...

...

used to> it. What Boost.Test really need is to document new release. And this is what we should be targeting. New features and new docs look and feel will make it all worthwhile.

Boost.Test is a key library - because nearly all other libraries have come to depend on it.

Testing is central to Boost's quality.

So I believe it is unwise for its maintenance to be in the hands of a single maintainer. Boost.Test should be 'community maintained' by consensus.

Changes to Boost.Test risk causing much trouble for many libraries, so change needs to be managed better than in the past.

So the current Boost.Test should be frozen so that no library author is suddenly forced to deal with any change to Boost.Test.

Any proposed improved version, called Boost.Test2 perhaps, should be subject to a FULL review of code, test, examples, and its documentation.

And it should have a small team of maintainers.

Library authors will be free to switch to Boost.Test2 (Boost.Test3...) when they find it useful and convenient.

Paul

PS Boost.Test feels much more complicated than most users need. So we might have a Boost.MiniTest too?

There is the lightweight_test.hpp in the boost/details directory. I have used this for my own testing needs.

Edward Diener writes:

...

PS Boost.Test feels much more complicated than most users need. So we might have a Boost.MiniTest too?

There is the lightweight_test.hpp in the boost/details directory. I have used this for my own testing needs.

It is indeed lightweight. Simpler? I do not think so. Not from user prospective. In fact I believe the test module, which uses this header, can be compiled using regular UTF include, with maybe one line change (define test case instead of main). Gennadiy P.S. This is if you compare with release version of Boost.Test. Trunk version of Boost.Test is in fact simpler from user prospective.

Gennadiy Rozental writes:

Paul A. Bristow writes:

...

and it's what I use for everyday work, and I'm sure I am not the only one doing this. So I'd like to see Richard's documentation of the current release Boost.Test adopted now.

And I'd like to see a documentation which covers full library, not part of it. And the one which covers latest state of the library, not the version from 5 years ago.

It's not the version from 5 years ago; it's the version in the latest release today! I don't know why you keep insisting otherwise. Sure, the trunk may have had new changes for X years, but the trunk is never released. Until your version is merged to release it remains the version of tomorrow, not today.

What about next release? Do you think it is a good practice if we release these docs now and then something completely different half a year later?

Absolutely. The docs should be the best available documentation for the code that ends up in the release. When the new version ends up there, then we update the docs to match. Alex -- Swish - Easy SFTP for Windows Explorer (http://www.swish-sftp.org)

[Please do not mail me a copy of your followup] boost@lists.boost.org spake the secret code <341AF96D-DAFD-424A-B5BD-86C042881F53@comcast.net> thusly:

The docs for the new version must be ready when the code is merged to release, not started after.

Even more reason to take my docs *today* for Boost 1.56 as they document what *is* in release. Honestly, I think it will be stupid simple to extend/modify the existing docs in quickbook than writing docs for new features in XML. -- "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

Bjorn Reese writes:

On 01/12/2014 10:19 PM, Gennadiy Rozental wrote:

...

...

PS Boost.Test feels much more complicated than most users need. So we might have a Boost.MiniTest too?

I never really understood these claims, without any specific examples. I

am

...

obviously biased, but show me "simple" library and we can discuss it. Even "hidden" boost alternatives - they are not simpler from user standpoint, they require as much typing (if not more). They are "lighter" indeed from compiler standpoint, but there is a price you pay for this.

Here is an example (requires C++11 though)

https://github.com/martinmoene/lest

Example of what? How is this any simpler? ------------------------------------- const lest::test specification[] = { "Empty string has length zero (succeed)", [] { EXPECT( 0 == string( ).length() ); EXPECT( 0 == string("").length() ); }, "Text compares lexically (fail)", [] { EXPECT( string("hello") > string("world") ); } }; int main() { return lest::run( specification ); } ------------------------------------ vs. BOOST_AUTO_TEST_CASE( my_test ) { BOOST_TEST( 0 == string( ).length() ); BOOST_TEST_MESSAGE( 0 == string("").length(), "Empty string has length zero (succeed)" ); BOOST_TEST_MESSAGE(string("hello") > "world", "Text compares lexically (fail)" ); } ------------------------------------ Not only Boost.Test version is simpler, it is also smaller, easier to understand, easier to extend, more flexible and provides better output in general. On top of than it simply does not look weird with all these [] {} spread all over your example. And I am not talking about all the other features UTF has, that this library does not even come close to replicate. Gennadiy

[Please do not mail me a copy of your followup] boost@lists.boost.org spake the secret code <52C6B3EA.40208@pabigot.com> thusly:

This says it documents version 1.22, but I can't tell whether that's just because Boost.Test isn't independently versioned and the last content update was in Boost 1.22.

It's the version of Boost.Test -- I think this should be 1.21 instead of 1.22, however. See http://www.boost.org/doc/libs/1_55_0/ I originally was working from trunk, but there's a whole bunch of stuff that is in trunk that isn't in release so with this snapshot I rescynchronized to the release branch.

The develop branch has over 200 changes that have accumulated since 2009, and as I understand how Boost releases are done it's this branch that gets the most road time, even though it isn't what gets released.

I really don't yet understand what is going on with this library in terms of how it is being maintained and enhanced. Unfortunately the maintainer is not very responsive.

Or maybe those changes don't actually affect users at all, though the develop branch has commits that discuss a new implementation. I'm still pretty confused about how Boost.Test evolves.

Yep. -- "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

[Please do not mail me a copy of your followup] boost@lists.boost.org spake the secret code <52C6FB82.30106@wanadoo.fr> thusly:

Le 03/01/14 18:10, Richard a écrit :

...

[Please do not mail me a copy of your followup]

boost@lists.boost.org spake the secret code <52C6B3EA.40208@pabigot.com> thusly:

...

This says it documents version 1.22, but I can't tell whether that's just because Boost.Test isn't independently versioned and the last content update was in Boost 1.22. It's the version of Boost.Test -- I think this should be 1.21 instead of 1.22, however. See http://www.boost.org/doc/libs/1_55_0/ This is just the first version of boost where Boost.Test appeared.

Ah, good catch. I'll correct that, thanks. -- "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

[Please do not mail me a copy of your followup] Thank you Mathieu for your detailed feedback. Mathieu Champlon spake the secret code <52CA700F.5020104@free.fr> thusly:

* source code links

When clicking on a source code link (any of the "Example source code" of the tutorials section for instance) my browser (firefox) downloads the file and attempts to open it using Visual Studio. I would rather be able to display the source code as html for a quick look instead.

I think when the code gets deployed to the web site, you end up seeing a browser-ified version of the source code. For instance, the existing links to source files appear this way on the web site, but I cannot find any indiciation that the quickbook source for other libraries, or the existing non-quicbook documentation for boost.test, does anything special to provide this.

* tutorials/testing_with_fixtures.html

The first example has a constructor and destructor for the fixture. While it's explained a little further that the default ones are fine here (and it should be obvious to a seasoned C++ developer), I fear that beginners who skim through the documentation will simply copy-paste this into their fixtures cluttering their code needlessly. Ideally having it the other way around (start with a simple fixture without constructor/destructor, then complicating things further) would be better, but maybe just moving the "In most cases, the setup will be a little more involved than just creating an instance variable and there will be some work done in the constructor of the fixture. We could simply use the default constructor and destructor of our fixture in this case. We've written the constructor and destructor explicitly to emphasize that this is where setup and tear down occur. " part into a "Note" right after the code would prove enough ?

So if I might paraphrase -- you're saying to display best practices first and make a note of where the setup/tear down code would appear?

* tutorials/running_selected_tests.html

I find "We can list the available tests in a test executable with --report_level set to detailed" a bit misleading as it doesn't just list the tests but still primarily executes them.

Yes, the trunk version of boost.test has a specific option for listing the tests called --list_content and not executing them. I'm not a fan of the name of this argument, but it is present on trunk and not on release. When I originally wrote this documentation it was based on trunk but I rebased it on release in order to get it moving forward.

Maybe rephrase it to something along the line of "Executed tests can be listed with --report_level set to detailed when running a test executable" ?

I'll reword this to say that the tests are executed as well as test names shown.

Is there any reason why you didn't mention using --run_test=hello_world_* first in order to filter on the test case names instead of jumping into test suites ?

I was using this as a way to introduce test suites :-).

I personally rarely use test suites because I usually use a naming convention like the one you introduced in a previous tutorial.

If you prefer that style of test organization, was the explanation in this tutorial good enough for you to see how to use that style?

* guide/compilation/minimal_header.html

In the "Meaning" column I fear that for instance "the test fails and test execution terminates" may leave a (perhaps non English native) reader wondering whether it aborts the current test or the test application ?

I can reword this for more clarification.

* guide/test_case_design.html

Maybe add a link to http://en.wikipedia.org/wiki/Test-driven_development to "(...), using test-driven development" ?

Good idea. More linking never hurts.

The Visual Studio configuration snapshot is a bit big in my opinion :)

It is native size. Were you thinking that providing a smaller, filtered version of the screen shot with the image being a link to the native size version?

Under "Goal: Repeatable Test" a bullet point list doesn't display properly.

Ah. Good catch.

* guide/testing_file_io.html

Just for the record I found writing tests with files to be one of the recurring pitfalls where manipulating actual files does indeed help, because when abstracting the file system things like re-entrance and file locking can be easily remain untested.

This is why I talk about acceptance testing being an integral part of any plan for automated testing. Unit tests alone are not enough because they exercise pieces of the system in isolation; you still need some sort of automated tests that bring all the pieces together and exercise them as a whole.

Any reason for the "extern" when declaring text_files ?

It is a function with external linkage. I don't want to declare it as a local function, but one that is provided externally. Do you feel that this is a leftover "C"-ism?

I believe the static for defining ARBITRARY_DIRECTORY_NAME and all isn't needed. Also the upper case names are usually reserved for macros (in Boost).

That may simply be a matter of style -- I picked this up from "Modern C++ Programming with Test-Driven Development" where he advises that using named constants for arbitrary inputs helps make it clear that the actual value used in the test isn't important so much as how that value appears in inputs and expected outputs. Regarding the casing of the identifier, I was falling back on constants being all caps, but I'll consult the boost style guidelines and adjust per their recommendations.

* guide/mocking_collaborators.html

Being the author of turtle I certainly appreciate the spotlight here, but isn't this part a bit out of Boost.Test documentation scope ?

It is, but mocking objects is too important to be left unmentioned. Since Turtle is designed to work directly with Boost.Test I wanted to give it a mention.

* guide/testing__main_.html

Again, any reason for the "extern" ? I'm just thinking it might confuse beginners.

Same as above.

* reference/test_case/boost_test_case_template.html

The fact that 'signed_types' is defined elsewhere is a bit odd especially since this page comes first when browsing the reference pages using the "next" button. Also 'unsigned_types' doesn't show up anywhere as it's simply not included. Maybe move both to the BOOST_TEST_CASE_TEMPLATE page or add them to both relevant pages ?

OK, I'll expand this example to be more complete when viewed standalone.

* reference/test_suite/boost_test_suite.html

manual_registration.cpp starts with a "using namespace boost::unit_test;" which doesn't appear in the documentation making it difficult to understand where the functions come from.

OK. I'll revise the examples to avoid using namespaces in order to make it more obvious where functions originate.

* reference/assertion.html

There is a typo in the note e.g. "be defiend" instead of "be defined".

Good catch. I will run a spell checker on everything to make sure I find any other typos like this.

* reference/assertion/*

None of the pages provide links to the source code files, is it on purpose ?

I thought the example snippets as they stood would be sufficient. I can certainly link to the example source file.

* reference/assertion/_boost____level___close_.html and reference/assertion/_boost____level___close_fraction_.html

Both have the exact same description and example code. An explanation on how they differ would certainly prove useful as this is probably one of the most asked question about Boost.Test on the mailing lists. Also a note about when to use BOOST_level_SMALL instead would be nice.

The floating-point comparison is the one area where I still need to write something real instead of just a placeholder. This is the last area that I have yet to finish.

* reference/assertion/boost_level_equal.html

In example_equal_custom_compare there's an extra space in the first initialization which might be confusing.

Which space are you referring to? The space between the definition of the string s and the first assertion?

Also I don't get how the comment is relevant given that operator== uses std::string to make the comparison ?

The standard library provides operator== and operator<< for std::string, so BOOST_REQUIRE_EQUAL can be used without requiring you to define these. For your own custom type you'll have to define them.

* reference/assertion/_boost____level___equal_collections_.html

I believe "static" to be deprecated at a namespace level ?

Static linkage to a function means that it is only visible within that single compilation unit. However, since generate_list is the system under test, this may be a little confusing. I could separate it into another compilation unit and give it a head, but then the whole example becomes much more complicated being spread across three source files, a new static library and an executable. For the purposes of making a small illustrative example I felt that was overkill.

I would personally rather use BOOST_REQUIRE_EQUAL_COLLECTIONS( boost::begin( expected ), boost::end( expected ), boost::begin( actual ), boost::end( actual )); which has the clear advantage to cover all the cases, but I understand the need for more "raw" examples.

There is a feature request from 4 years ago(!) for exactly this: https://svn.boost.org/trac/boost/ticket/3871 I recently tried to read the Boost.Range documentation and I confess that I didn't exaclty find it accessible at a quick read. In this documentation I wanted it to be as standalone as possible and not drag the reader unnecessarily into other libraries. In this case I think that the vast majority of C++ programmers are not going to have a problem with container.begin() or container.end() whereas many may not have seen boost::begin(container) and boost::end(container). Is the motivation for this suggestion to guide C++ programmers more towards C++11 style usage where std::begin() and std::end() are available? I can see how their use for fixed length arrays is preferable over the old "sizeof(array)/sizeof(array[0])" business, but how exactly is it preferable for containers where we have begin() and end() member functions?

* reference/assertion/boost_level_exception.html, reference/assertion/boost_level_message.html and reference/assertion/_boost____level___predicate_.html

The "static" aren't really needed, I believe.

See above. They are given static linkage to intentionally limit the accessibility of their names.

* reference/assertion/_boost____level___small_.html

Maybe explain the unit of the tolerance for completeness and coherence with BOOST_level_CLOSE* ?

This is part of the remaining area that needs to be done. -- "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

On Jan 7, 2014, at 8:19 AM, Mathieu Champlon wrote:

On 06/01/2014 20:07, Richard wrote:

...

...

* guide/test_case_design.html

(...) The Visual Studio configuration snapshot is a bit big in my opinion :) It is native size. Were you thinking that providing a smaller, filtered version of the screen shot with the image being a link to the native size version?

It's just the image is quite big and the only useful information are the two lines at the top. But I know the window cannot be resized and downsizing the screen shot itself will probably reduce the quality.

Perhaps cropping the bottom from it would help? ___ Rob (Sent from my portable computation engine)

Alexander Lamaison writes:

...

I keep asking you to collaborate on something which we can actually release. I am not sure why you keep ignoring me.

Richard didn't ignore you. He explained that he documented the version of Boost.Test that users are actually using. The version that ends up in the releases.

The new version that needs to be releases IS the one that will appear in a release and the one which is significantly different.

...

It's no use to the users if the documentation describes what may happen at some unspecified point in the future, but doesn't match the code in front of them.

It is not some unspecified time in a future. New version is ready and just need to be fitted with new documentation.

...

2. This is not a Boost.Test documentation - this is is boost unit test framework documentation

You are missing the whole original point of layering in boost.test design. You are missing description of all the other independent layers. In general I think you are missing quite a few other things as well.

The problem with the original documentation was that so much of it was about how the UTF was implemented. No-one cares. Users only want to know how to use it to write unit test with Boost.Test. Back in the day I had to learn that from Richard's blog.

You can probably have number of complains about existing implementation. This is NOT one of them. If anything it was lacking reference part and Richard's version improve on that. Would you care to show an example?

I could respond to each of your criticism but I think I'll just end by saying that, if a team have scrutinised this documentation for months, finding it greatly improved, and the user reception is overwhelmingly positive, perhaps Richard has some skills in the documentation area.

I am not argue his skills. I just want to apply them in a right direction. Gennadiy

To me, this feels kinda backwards. You've implemented something without explaining it to anyone first or getting their feedback on the design. We have no idea whether or not it will be an improvement over the existing library or whether or not anyone will even like it and want to use it.

He did discuss the new features with the mailing list, and even presented it for a min-review: http://boost.2283326.n4.nabble.com/Boost-Test-updates-in-trunk-need-for-mini... http://boost.2283326.n4.nabble.com/test-BOOST-TEST-universal-testing-tool-td... -- View this message in context: http://boost.2283326.n4.nabble.com/Call-for-Review-Boost-Test-documentation-... Sent from the Boost - Dev mailing list archive at Nabble.com.

Richard writes:

[Please do not mail me a copy of your followup]

boost <at> lists.boost.org spake the secret code <1389378320565-4657604.post <at> n4.nabble.com> thusly:

...

He did discuss the new features with the mailing list, and even presented it for a min-review:

http://boost.2283326.n4.nabble.com/Boost-Test-updates-in-trunk-need-for-

mini-review-td4637343.html

Thanks for that (I am puzzled why Gennadiy didn't provide this to me; oh well).

That was 15 months ago and I wasn't subscribed to the developer list at that time.

Frankly, I did not realize you are so new to the list.

Still, the point remains that the features in 1.55 release branch are what everyone is using today and regardless of whatever new features may be introduced, those existing features *must* be documented and explained the new documentation I've written does a much better job of making that information easy for people to find.

Those existing features are documented one way or another. We do not want new documentation to include 3 different ways of doing the same thing. New documentation should cover new recommended way of using the library. As for the older interfaces, we can have one page which list them and refer to the previos release for description. If you insist we can probably refer to your version, but it should be very clear that this is not the way one is expected to use the library. New user of Boost.Test should not be using these anymore. I am still open to work with you on this. Given your familiarity with the library we should be able to present a version of Boost.Test with the docs and ask for mini-review of this new version soon enough. Regards, Gennadiy

Richard writes:

[Please do not mail me a copy of your followup]

boost <at> lists.boost.org spake the secret code thusly:

...

Richard writes:

1. First and foremost: it is pretty much completely irrelevant Trunk version of boost.test will require us to rewrite 90% of what you

did.

I disagree. I wrote 99% of everything here based on trunk

No. It is not.

which still has all the stuff I documented -- and must have all of that in order to be backwards compatible with release.

Sure it will. But this is not what we want users to use. New version has much better tools and interfaces, more runtime parameters, new subsystems etc.

What you have done in trunk is add an unknown quantity of new, untested features -- untested in the sense that noone is using them so they have no user feedback as to the quality or usefulness of their implementation. You haven't documented them and you haven't solicited anyone to perform any pre-release evaluation of those features.

The plan was to write docs and ask for review. We can't ask anyone to review new library features without some form of documentation. Otherwise all the features are tested - I have unit tests for them.

I don't feel compelled to document something for which there appears to be no design documentation, no statement of completeness, no rationale for existing and has unknown amounts of bugs in it because noone is really using it.

You did not feel compelled to ask the question. Would you care to point me to a single boost library developer, who wrote design document before implementing library changes? And do you think if I would be one like this, I would not finish whole docs by now? The procedure is to make the changes, test them, write some docs. Ask for review if changes are significant enough. I hoped we can collaborate on last part parts. Before library is out there, there obviously will be no one using it.

...

I keep asking you to collaborate on something which we can actually release. I am not sure why you keep ignoring me.

Funny, I could say the same thing. I wrote my tutorial blog posts 4 You responded saying that you would include a link to those tutorials in the documentation: http://article.gmane.org/gmane.comp.lib.boost.user/49151

That never happened.

You are not the only one. I have a long list of links with references to various blogs, web pages etc. I still plan to have a separate page in docs, with all the "web wisdom" mentioned. That said, documenting new features is still a priority.

On May 1st, 2013 I asked for early reviewers of this rewrite: http://article.gmane.org/gmane.comp.lib.boost.devel/240855

You never replied to that, either in the list/newsgroup or in email. All the people that replied were added to my list of reviewers and have been getting updated snapshots along the way: Tom Kent, Alexander Lamaison, Paul A. Bristow and Julian Gonggrijp (apologies if I misspelled any of your names). I went through at least 7 iterations with those early reviewers, incorporating their feedback along the way.

I did not reply because in our previous conversion (few month before that) I ask for you to work on a new version instead of spending time on old one and you ignored me. I did not see a reason to waste time reviewing something which is no help for new release.

I have also sent you email to which you never responded.

Where did you send it? and when? I obviously expressed interest in talking with you. All people who are interested, can reach me easily.

I found documentation bugs in the bug tracker that had been sitting there for 4 years with no movement. (I fixed them all in my rewrite.)

Most of them are already fixed in a trunk version of Boost.Test docs.

Questions get posted about Boost.Test on the user or developer mailing lists and go unanswered by you and given the current state of affairs, you were pretty much the only one that could answer them.

There are few threads from last several month in my "to answer" bin indeed. I am very busy and not always can get to it right away. If question is answered fine by someone else, I am not going to chip in second time.

...

2. This is not a Boost.Test documentation - this is is boost unit test framework documentation

I find this to be a distinction that is both confusing and unnecessary to users of Boost.Test. Similarly, I removed all reference to "test

I do not think you can make this decision.

tools" because this terminology is non-informative (tool is too generic) and not consistent with the terminology generally in use -- the industry calls these programming constructs assertions and I see no reason why Boost.Test should deviate from industry standard terminology.

This is fine. Especially since in a new version most of it will come to a single type of assertion.

...

You are missing the whole original point of layering in boost.test design.

In 4+ years of using Boost.Test, I haven't found that I ever cared about this.

Well, you are not the only user of the library. There are lot more people using these features than you think. UTF is obviously the most used part of Boost.Test, but not the only one.

When I talk to other people about the existing documentation, they found all this discussion of these layers to be distracting and irrelevant.

Those 5 people you were talking to are not the only users of the library.

So I treated them as an internal implementation detail that users didn't need to know about.

It is not. It is part of public interface and needs to be properly documented.

...

You are missing description of all the other independent layers. In general I think you are missing quite a few other things as well.

<shrug> In my opinion, what remains is what is important and necessary in order to use this library for unit testing.

In my opinion - it's not.

...

3. You eliminated the examples. I liked original examples much better with their output etc.

I didn't eliminate examples, I replaced them. Everything that you need to do as a user of this library has an example. For cases where the output is important, the output is present in the documentation. I don't see much utility in demonstrating the kind of message you get from every single assertion when it fails. I could be convinced otherwise, but as a user of this library for 4+ years I haven't needed it. You simply look at the failed message and you know what to do without reading documentation.

In my experience of supporting this library (which is much longer)expected output is always a good thing. I would rather keep all of these.

...

4. You made quite a lot of description more terse

This was intentional. The existing documentation used pages to describe what could be explained in a paragraph or two, particularly for the reference section.

Well, this is a matter of opinion. I am willing to discuss this.

...

Take runtime parameters for example. Where I had few pages you left only few paragraphs. I find new description very lacking.

Yet other reviewers have not commented on this at all. That tells me that the extra detail simply isn't needed.

You reviewers are already experienced users of the library. They may not have an unbiased view on this.

...

5. I understand you have your own favorite mocking library, but it is not part of Boost.Test (not yet at least).

Correct, but once you start practicing TDD in C++ you quickly get to the point where you need a mocking library. Turtle is designed to work seamlessly with Boost.Test and is proceeding towards being submitted to Boost. There are other mocking libraries out there and I'm happy to link to them as well from the documentation, but the ones that I've used in the past required more boiler-plate than Turtle. gmock can no longer be used with Boost.Test because using gmock now requires the use of gtest. MockCpp requires more boilerplate and hasn't been updated since Oct 2011. There are probably others; while I have a personal preference for Turtle that doesn't mean I'm adverse to linking to any other mock libraries.

Let's review this separately. I have a preference to what I already have on Boost.Test obviously. In any case We should mention all possible candidates (including older version of gmock if if is applicable).

...

6. I think quickbook navigation is seriously lacking.

Specific suggestions are welcome.

Didn't you just delete one: let's consider something along the lines of Boost.Preprocessor. Regards, Gennadiy