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

[Steven Schveighoffer]

On Mon, 24 Jan 2011 16:43:39 -0500, 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.

My proposed enhancement is fully backwards-compatible, so it's no biggie  
if it's not in the first iteration.  I was simply thinking in terms of my  
projects where I use unit tests to test several functions that interact  
with eachother, those would make nice examples.  But I could only attach  
them to one function (or repeat them).

-Steve