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

[Jonathan M Davis]

On Monday 24 January 2011 12:15:07 Andrei Alexandrescu wrote:
> On 1/24/11 1:50 PM, Jens Mueller wrote:
> > Jonathan M Davis wrote:
> >> I think that it's been discussed a time or two, but nothing has been
> >> done about it. It wouldn't be entirely straightforward to do.
> >> Essentially, either a unittest block would have to be generated from
> >> the Examples section in the documentation, or you'd have to have some
> >> way to indicate that a particular unittest block got put into the
> >> documentation as an Examples section. It's certainly true that it would
> >> be ideal to have a way to avoid the duplication, but we don't have one
> >> at the moment, and it hasn't yet been a high enough priority to sort
> >> out how to do it and implement it.
> > 
> > I see. I understand that it does not have high priority. Just wondered
> > whether ...
> > 
> > Jens
> 
> The change is much simpler than what Jonathan suggests. A change can be
> made such that any unittest preceded by a documentation comment is
> automatically considered an example.
> 
> /**
>   Example:
> */
> unittest
> {
>      writeln("This is how it works.");
> }

Well, I did say that either the documentation example had to be turned into a 
unittest block or a unittest block had to be marked in some way to indicate that 
it should be turned into an example and then have it put into the documentation 
that way. You're suggesting the latter of the two (which is probably the better 
choice). I completely agree that this is an important topic. It's just that it's 
fallen by the wayside thus far.

Personally, I'm always having to copy-paste example back and forth between the 
documentation and the unittest block in order to make sure that they're in sync, 
and even then I still screw up sometimes. So, I'd definitely like a solution 
which makes it so that you don't have to duplicate the code/example like that.

- Jonathan M Davis