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

[Please do not mail me a copy of your followup] boost@lists.boost.org spake the secret code thusly:

On 20 February 2014 05:54, Richard wrote:

...

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

boost@lists.boost.org spake the secret code 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-...

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

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