Showing unittest in documentation (Was Re: std.unittests

[spir]

On 01/25/2011 11:10 AM, foobar wrote:
>> 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.

Seems doc meta-languages are usually too complicated and this complication 
never helps meeting practicle needs. Think at Walter' repeted argument that 
unittests are highly used precisely because they are that simple. The same 
applies to doc, imo. I would thus favor an extremely simple doc feature, along 
with use recommandations, and stricter guidelines for public/std packages.

About the current issue of examples applying to several elements of a module, a 
simple solution would be to have an example section at a standard location (eg 
at the bottom, or just below the general module doc). Each example there would 
be /named/, so that function docs could point to them. A refinement would make 
example names link targets and pointers to them link pointers.
In the same vein: named unittests would allow pointing to them, and possibly 
generate link targets in the html doc, under their own name.

	/** blah
	* blah blah blah
	* blah blah blah
	*
	* Example:
	*     ...
	* See also:
	*     example $(target MapFilterCombination)
	*     unittest $(target testFilter)
	*/

	T[] filter (T) (T[] elements, bool function (T) predicate)
	{
	...
	}

Denis
-- 
_________________
vita es estrany
spir.wikidot.com