Showing unittest in documentation (Was Re: std.unittests

[Jonathan M Davis]

On Tuesday 25 January 2011 02:10:49 foobar wrote:
> Jonathan M Davis Wrote:
> > On Monday 24 January 2011 15:27:08 foobar wrote:
> <snip>
> 
> > > Unit-tests are defined on a module level, not a function level, hence I
> > > would expect to see the unit-tests that serve as examples to appear in
> > > an examples section on the page the documents the module itself. In
> > > the online docs I would expect the function names used in the example
> > > to be links to the individual function doc and for each function have
> > > a list of links to examples it participated in. This should be
> > > automatic and the user shouldn't need to provide the "list of
> > > functions documented in this example".
> > > 
> > > Just my two cents..
> > 
> > Examples almost always go with functions. The whole point is to avoid
> > having to have the function examples both in the documentation and in a
> > unittest block. It would be a huge mess to try and put all of the
> > examples in the module documentation. I shudder to think what that would
> > look like for std.algorithm - or even worse (_far_ worse), std.datetime.
> > The simple syntax of
> > 
> > /++ Example +/
> > unittest
> > {
> > }
> > 
> > 
> > making that unittest block go in the documentation of the preceding
> > function should work just fine. We already have /++ Ditto +/ which puts
> > a function in with the preceding function's documentation. So, having
> > /++ Example +/ on top of that isn't much of a stretch.
> > 
> > - Jonathan M Davis
> 
> Depends on what you mean by example.
> It seems to me that by "Example" you mean something like a line or two that
> just show how to call a function. I meant by "Example" a more complicated
> small program that exercises several functions in the module. something
> more like a tutorial for using the module.
> 
> For my kind of example you need to provide just one or two examples for a
> module, it makes more sense to put it at the module level and also in a
> unit-test block.
> 
> Your kind of example looks less useful to me and I personally wouldn't
> bother with unit-testing it.
> 
> I guess it's just personal style and preferences.

Look at std.algorithm if you want to see typical examples of examples (no pun 
intended). _Those_ are the kind of examples that we're worried about. And yes, 
they're generally examples per function. And if you _don't_ unit test them, then 
you risk them being incorrect code. By having the be in a unittest block which 
gets turned into an example, you know that the code is valid and that it works. 
And you don't have to worry about the example and the unit test being of sync.

Very little in Phobos would benefit from a module-level example as you describe. 
Most modules hold functions which are loosely related at best (std.algorithm and 
std.string being prime examples). So, having a module-level example wouldn't 
really be worth much.

- Jonathan M Davis