automatic code examples in documentation

[Jonathan M Davis]

On Friday, October 15, 2010 16:49:06 Tomek Sowiński wrote:
> Andrei Alexandrescu napisał:
> >> Let's drill down on this:
> >> 
> >> /// The ultimate foo.
> >> void foo();
> >> 
> >> /// The test.
> >> unittest { ... }
> >> 
> >> What would be the<dl><dt><dd>  outline of the above snippet?
> > 
> > From a ddoc perspective this should be the same as:
> > 
> > /** The ultimate foo.
> > 
> > The test.
> > ----
> > ...
> > ----
> > */
> > void foo();
> 
> I see. That means unittests summarizing the whole of module's goodies would
> have to be at the top, but that's passable. Otherwise it's a superb idea.
> 
> As I mentioned in bugzilla, it opens the opportunity to kill the unittest
> naming problem with the same stone:
> 
> void foo();
> 
> unittest(owner) {
>   Log.info("Testing " ~ owner.stringof ~ "...");
>   scope(exit) Log.info("Testing " ~ owner.stringof ~ " complete");
> }
> 
> The syntax takes after the out(result) contract. 'owner' is an alias to the
> preceding symbol. The overall ROI looks positive, eh?

I'd actually consider that to be a bad idea.

1. We should be able to name unit tests independently of any function or 
functions that they're testing.

2. It should be fully possible to have more than one unit test for a single 
function or have one unit test for multiple functions and have names on those 
unittest blocks.

Only a small portion of unit test code necessarily makes sense as an example. 
So, while having syntax that indicates that a test goes with a particular 
function as its example is a good idea, remember that there are going to be 
plenty of other unittest blocks that are _not_ intended as examples. I'm not 
sure that we want to mix up named unit tests and unit tests which become 
examples in ddoc comments.

I fully support the syntax of

unittest(testname)
{
}

but I don't like the idea of

unittest(owner)
{
}

I think that it would make far more sense to do it in another way, perhaps

@example
unittest
{
}

or to have an example unit test with a name

@example
unittest(testname)
{
}

Or we could simple use a ddoc marker on it as Andrei suggested:

///
unittest(testname)
{
}

The one issue is templates. Putting a unittest in a block in a template doesn't 
make much sense for examples. For an example, you'd need to be dealing with a 
concrete template instantiation, while a unittest block within a template type 
would be for all instantiations of that template. So, in that case, being able 
to indicate an owner would certainly be useful. But I'm loathe to do it in away 
that makes it harder to add proper unit test names. Maybe what we do is make it 
so that unit test names which match a function name within that module are 
associated with that function as its example and the test function is given the 
same name as the function with _example tacked on or something similar. So,

void func() {}

unittest(mytest)
{
}

unittest(func)
{
}

would result in a named unit test mytest which was not an example, and a named 
unit test func_example which was the example for func() and was put in its ddoc.

- Jonathan M Davis