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
