[Please do not mail me a copy of your followup]
boost@lists.boost.org spake the secret code
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