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

[Andrew Wiley]

On Mon, Jan 24, 2011 at 3:43 PM, Andrei Alexandrescu <
SeeWebsiteForEmail at erdani.org> wrote:

> On 1/24/11 3:36 PM, Steven Schveighoffer wrote:
>
>> On Mon, 24 Jan 2011 16:03:24 -0500, Andrei Alexandrescu
>> <SeeWebsiteForEmail at erdani.org> wrote:
>>
>>> I find documented unittests attractive mainly because they're
>>> _simple_. As soon as we start to add that kind of stuff... exponential
>>> decay.
>>>
>>
>> It's only not simple if you want it to be. The /** Example: */ simple
>> method is also covered. Let's also not forget that the end result is
>> generated documentation, not the comments. All this 'non-simplicity' is
>> going to be hidden there.
>>
>
> I think I worked too much with Walter because I'm almost thinking on his
> behalf. The thing is, at this point Walter (and me too) has a sympathy for
> language changes that remove undue limitations, and an aversion for language
> changes that introduce new stuff that the user would learn.
>
> So if we go to Walter with: "Hey, we can currently document a variety of
> declaration, but not unittests. Let's allow documenting unittests as well"
> he'd be like, "heh, that sounds great... okay". But if we go to him with
> "hey, here's this new feature that needs these syntactic additions and these
> semantics and and has several nontrivial effects and..." then the chance of
> adoptions are seriously harmed.
>
> Let's stick with KISS. Though I agree there are many improvements that can
> be brought to ddoc, I don't want a new feature, only to be able to document
> unittests.


Here's another approach:
When you think about it, what we're after is tagging unit tests as code
examples, so why not do exactly that with annotations?

@example(Foo.bar)
unittest {
//...
}

It means there are no new keywords to worry about, and this feels more like
a job for metadata than a language feature to me. We'd probably have to
formalize adding parameters to annotations, but that's pretty much
inevitable if they're ever going to reach a useful state.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20110124/6b31f517/attachment-0001.html>