Showing unittest in documentation (Was Re: std.unittests

[Jens Mueller]

Jonathan M Davis wrote:
> On Monday 24 January 2011 15:27:08 foobar wrote:
> > Steven Schveighoffer Wrote:
> > > 
> > > This only makes sense if:
> > > 
> > > 1. The unit test immediately follows the item being documented
> > > 2. The unit test *only* tests that item.
> > > 
> > > The second one could be pretty annoying.  Consider cases where several
> > > functions interact (I've seen this many times on Microsoft's
> > > Documentation), and it makes sense to make one example that covers all of
> > > them.  Having them 'testable' means creating several identical unit
> > > tests.
> > > 
> > > One way to easily fix this is to allow an additional parameter to the
> > > comment:
> > > 
> > > /**
> > > Example(Foo.foo(int), Foo.bar(int)):
> > > */
> > > unittest
> > > {
> > > 
> > >     auto foo = new Foo;
> > >     foo.foo(5);
> > >     foo.bar(6);
> > >     assert(foo.toString() == "bazunga!");
> > > 
> > > }
> > > 
> > > The above means, copy the example to both Foo.foo(int) and Foo.bar(int)
> > > 
> > > An alternative that is more verbose, but probably more understandable:
> > > 
> > > /**
> > > Example:
> > > Covers Foo.foo(int)
> > > Covers Foo.bar(int)
> > > */
> > > 
> > > Of course, a lack of target just means it applies to the item just
> > > documented.
> > > 
> > > One other thing, using writefln is considered bad form in unit tests (you
> > > want *no* output if the unit test works).  But many examples might want
> > > to demonstrate how e.g. an object interacts with writefln.  Any
> > > suggestions? The assert line above is not very pretty for example...
> > > 
> > > -Steve
> > 
> > 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.

I feel the same.
When I propose how it should be and how it is right to me I feel a bit
bad. Because I have not contributed anything besides talking. That's why
in the end I always will follow the people's advice who actually do the
work. I mean if Walter decides to leave it as it is, it's his decision
until somebody provides a patch. He does the work. Who am I to tell him
what he should do.

Jens