Showing unittest in documentation (Was Re: std.unittests [updated] for review)

Tomek Sowiński just at ask.me
Mon Jan 24 14:12:31 PST 2011


Steven Schveighoffer napisał:

>> BTW I consider this a very important topic. We have _plenty_ of
>> examples that don't work and are not mechanically verifiable. The
>> reasons range from minor typos to language changes to implementation
>> limitations. Generally this is what they call "documentation rot".
>> This is terrible PR for the language.
>>
>> Changing ddoc to recognize documentation unittests would fix this
>> matter once and forever.
>>
>> Last but not least, the "----" separators for code samples are awful
>> because no editor recognizes them for anything - they confuse the
>> hell out of Emacs for one thing.
> 
> 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.

Although coming from good intentions, it's just.. too much. The original
idea is very compelling without add-ons.

Often the interacting functions are members of the same class or at
least same module, so it's enough to place the unittest appropriately.
To cover remaining cases an artificial declaration may be introduced.

/// Uses of Foo.foo(int) and Foo.bar(int)
struct foo_and_bar_examples;

/// Example:
unittest { ... }

Both functions would simply link to the artificial symbol in their
ddocs.

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

I was thinking of mockFile.writefln(obj) but not sure if std.stdio can
handle it.

--
Tomek



More information about the Digitalmars-d mailing list