Re: [boost] Call for Review: Boost.Test documentation rewrite

Subject: Re: [boost] Call for Review: Boost.Test documentation rewrite
From: Mathieu Champlon (m.champlon_at_[hidden])
Date: 2014-01-07 08:19:23

On 06/01/2014 20:07, Richard wrote:
>> * tutorials/testing_with_fixtures.html
>>
>> (...)
> 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?

Yes.

>> * tutorials/running_selected_tests.html
>> (...)
>> 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?

The idea of using wildcards only appears at about 2/3 of the page and it 
looks almost as if it were a feature of test suites because the two 
sentences are on the same line:

"The names of the enclosing suites are separated from each other and 
from the test case name with a slash (/). The names supplied to 
--run_test also allow for wildcard matching (...)"

To me both test suites and wildcards are equally important and maybe 
they could be introduced at the same time, for instance rephrasing

"We can solve this problem by using test suites, which organize tests 
into a named group"

to incorporate wildcards as well, e.g. something along

"We can solve this problem by either using wildcards with --run_test 
when test names follow a regular naming pattern:
<example>
or by using test suites, which organize tests into a named group (...)"

>> * 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.
No big deal, never mind.

>> * guide/testing_file_io.html
>>
>> (...)
>>
>> 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 don't think there is any reason to use the extern keyword at all, see 
for instance 
http://stackoverflow.com/questions/11712707/extern-functions-in-c-vs-c

>> * 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?

     symbol const s1 = { "var" , 1 };
     symbol const s2 = { "var", 1 };

There is an extra space at the right of "var" for s1 compared to s2.

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

I meant about the comment in:

     symbol const s1 = { "var" , 1 };
     symbol const s2 = { "var", 1 };
     // If the compiler doesn't collapse multiple constants, then:
     // s1.name != s2.name;
     BOOST_REQUIRE_EQUAL(s1, s2);

While true, I don't see how that's relevant.
Or maybe you wanted to explain why operator== uses std::string instead 
of comparing 'name' pointers?

static bool operator==(symbol const& lhs, symbol const& rhs)
{
     return lhs.value == rhs.value
         && std::string(lhs.name) == std::string(rhs.name);
}

in that case maybe move the comment there?

>> 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>
>
> (...)
>
> Is the motivation for this suggestion to guide C++ programmers more
> towards C++11 style usage where std::begin() and std::end() are
> available?
>

Yes, but a more proper solution may be to introduce a 
BOOST_CHECK_EQUAL_RANGE similar to the one described in the ticket you 
linked.

>    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?
>

For the sake of uniformity I suppose, but don't bother the examples are 
fine as they are.

Thanks !
MAT.