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-23 21:16:13

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

boost_at_[hidden] spake the secret code
<CADJ=SEPWyZosZh=V1u95Upu_ERyHRaTeJ53Ku5CSRu-dPuY7gw_at_[hidden]> thusly:

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

I think reasonable people can disagree on whether this is better or
not :-).

>Your doc would be no worse then the original if it simply stated that
>these features existed. Anything else is an enhancement request...

I agree with this.

If I were going to need custom reports, I'd take the XML report output
and run it through a XSLT file before I spent time writing code, but
maybe writing C++ is easier for people than XSLT.

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

In other words, except for the missing hint, these aren't deficiencies
of my docs compared to the existing docs.

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

AFAIK, the existing documentation does not explain how to use the
implementation classes to traverse the test tree.  So this is an
enhancement.

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

Yes, appears to be a temporary outage.  Again, this is something that
the existing documentation does not explain at all, other than perhaps
hinting that you can have a custom report.

ok, so you want:

1) custom report format support
2) (and I assume, it's cousin) custom log format support
3) traversing the test tree

AFAIK, other than hints, these are all additions to the existing
documentation.  (In fact what I wrote about the report format is
already an addition to the existing docs.)

So achieving better than parity with existing docs would be to simply
say "You can customize the report output; see <this example>" and link
to that url.

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

Not sure what your use case is, but definitely listing out the tests
in your project and getting custom report or log output can be handled
without writing C++ code, albeit you might need to write some XSLT
code.

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

I think you raise some reasonable immediate points that can be
addressed by adding a few sentences.

Longer-term you're asking for new documentation on classes in the
library.  I think that is also a reasonable request, but it's beyond
the scope of what I'm trying to obtain with this change.

>>[I left out stuff about the Program Exeuction Monitor (PEM)]
>
>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.

Is it really?  To me, it's an implementation detail.  The main thing
you need to know about the PEM is that it attempts to intercept all
badness and capture that as a test failure: unix signal(2), Windows
SEH style exception, and C++ uncaught exception.

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

Yes, by "it" I'm referring to the PEM.
-- 
"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>