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

Subject: Re: [boost] [test] Looking for co-developer/maintainer
From: Darryl Green (darryl.green_at_[hidden])
Date: 2014-05-20 00:11:37

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

Agreed there is no explanation. But clearly the list of section headings
includes the heading *Custom report format support* as well headings
for  several other ways of controlling report output.
To that extent it documents that extensibility exists.
This is better than not mentioning the capability at all.
Your doc would be no worse then the original if it simply stated that
these features existed. Anything else is an enhancement request...

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

The *it* is to use your words *this advanced functionality* or to use
the words missing from your docs *custom report format support*.

I have needed to use other extension points.
I cited the couple of specific examples below (ones I'd found because
I needed to use the extension point and googled for any examples
- because there were no docs) to illustrate some specific values of *it*
that have clearly been used by more than one person...

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

Regardless of the question, the answer to the question requires use of the API
(or a commandline option that doesn't exist). The documentation should provide
answers, not questions.

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

I don't know what page you got from a cache but the page I (re)got just now
(absolutely not from a cache - via https to be extra sure) is exactly
about a custom
output format. Maybe a DNS issue or maybe a temporary outage?
The page documents by example how to use some
undocumented APIs to do something useful (to the author and me).

You have twice asserted that uses of the API can be replaced by use of a
commandline argument. This is not really true (it doesn't solve my use case)
but I do agree the commandline argument is an example of the use/control
of the lib via the API in question - a good reason to document it.

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

I agree it is unclear. I'm only trying to provide some clarity (with sources)
as to what is demonstrably already intended to be and in use as part of the
interface, so that the docs can make that clear.

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

Sure. I'm not complaining about the docs you have written,
or complaining that you lack omniscience :)

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

I agree it isn't used by itself. However knowing what it does (and some level
of how at the level of identifying what platform specific features it
uses) is useful.

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

Assuming this "it" use the program execution monitor, that is consistent
with my own experience, fwiw.