Re: [boost] [test] Looking for co-developer/maintainer

Subject: Re: [boost] [test] Looking for co-developer/maintainer
From: Richard (legalize+jeeves_at_[hidden])
Date: 2014-05-19 19:12:46

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

boost_at_[hidden] spake the secret code
<CADJ=SEP57oM7r3mBNY82gLVgHu=3Vjo=pKCZ=6EZZbfmCKD-HQ_at_[hidden]> thusly:

>On 20 February 2014 05:54, Richard <legalize+jeeves_at_[hidden]> wrote:
>> [Please do not mail me a copy of your followup]
>>
>> boost_at_[hidden] spake the secret code
>> <CADJ=SEMqYFoCaZi9m+MPzu1_n=4QD3Y3Yd1wDH526foFXuxSeA_at_[hidden]> thusly:
>>
>>>However docs on extending and using the lib beyond basic use cases
>>>(eg traversing the tests for producing custom result formats) are much
>>>needed.
>>
>> That's a reasonable request.  However, this information is missing
>> from the current documentation, so my version doesn't make things any
>> worse.
>>
>
>Yes it does. It doesn't even mention or imply that it is possible.
>There are hints that you can extend (yes, the docs are not good - but
>that is different from missing) for example:
>
>http://www.boost.org/doc/libs/1_55_0/libs/test/doc/html/utf/user-guide/test-output/results-report.html

When I browse that URL I just get a list of section headings.

In what way does this document extensibility?

As you say, the docs contain hints, but no explanation of how to do
it.  I've read through them.

>> I am curious how many people need this advanced functionality.  If one
>> person needs it, then it's lower priority than if a bunch of people
>> need it.
>
>Well, as you apparently talk to lots of boost test users - ask them.

I have.  Except for this specific thread, noone has stated that they
need this.

>All I know is that I needed it and others clearly have otherwise I
>wouldn't have found questions and answers including code examples on
>the web.
>It would be nice to have it in the docs.

Can we get back to specifics?  What "it" do you want in the docs?

>traversing the test tree:
>http://stackoverflow.com/questions/8550704/boost-unit-test-list-available-tests

This is actually not a question about traversing the test tree so much
as it is a question about how to list the available tests.  As the
maintainer pointed out, there is a new command-line argument that
provides this functionality.  (I actually had documented it in an
earlier snapshot, but took it out when I realized that this
command-line argument appears in no shipping version of the library.)

>custom log formats:
>http://www.eld.leidenuniv.nl/~moene/Home/projects/testdox/boosttest/

This page is actually dead now.  I had to get it from Google's cache
from May 1, 2014.  This is also not about a custom log format, but is
about getting the test names from the library so that documentation
can be created from those test names.  This is also serviced by the
--list-content argument.

>But regardless - Are we going to start voting for which public
>interfaces of boost libraries should be documented or can we take it
>as a given they all should be?

Because so much of the content of Boost.Test header files has remained
undocumented for so long, it is unclear what is an implementation
detail and what is an interface without documentation.

>You have argued quite strongly *against* documenting these features in
>this thread.

Meh.  I am not the author of the library, so I can only comment as a
user of the library since ~2005 what I perceive to be implementation
detail compared to useful API surface.  I added things that weren't
documented that I thought were important to know, like how to write a
custom predicate, among other things.

Off the top of my head, the main thing I left out were details about the
program execution monitor.  This is a mechanism implemented in Boost.Test
to ensure that the library can report errors as much as possible.  I don't
know anyone who uses this component by itself, but it was documented
before and I didn't spend any time documenting it in the rewrite.

Am I saying I *won't* document it?  No, I'm saying that in almost a
decade of using this library and in consulting with other programmers
who use this library in meatspace as well as mailing list space, I
have never talked to a single person who used it outside the library
itself.
-- 
"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>