Showing unittest in documentation (Was Re: std.unittests

[foobar]

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.