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.
