<div class="gmail_quote">On Mon, Jan 24, 2011 at 3:43 PM, Andrei Alexandrescu <span dir="ltr"><<a href="mailto:SeeWebsiteForEmail@erdani.org">SeeWebsiteForEmail@erdani.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<div class="im">On 1/24/11 3:36 PM, Steven Schveighoffer wrote:<br>
</div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="im">
On Mon, 24 Jan 2011 16:03:24 -0500, Andrei Alexandrescu<br>
<<a href="mailto:SeeWebsiteForEmail@erdani.org" target="_blank">SeeWebsiteForEmail@erdani.org</a>> wrote:<br>
</div><div class="im"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
I find documented unittests attractive mainly because they're<br>
_simple_. As soon as we start to add that kind of stuff... exponential<br>
decay.<br>
</blockquote>
<br>
It's only not simple if you want it to be. The /** Example: */ simple<br>
method is also covered. Let's also not forget that the end result is<br>
generated documentation, not the comments. All this 'non-simplicity' is<br>
going to be hidden there.<br>
</div></blockquote>
<br>
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.<br>

<br>
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.<br>

<br>
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.</blockquote><div><br></div><div>Here's another approach:</div>
<div>When you think about it, what we're after is tagging unit tests as code examples, so why not do exactly that with annotations?</div><div><br></div><div>@example(Foo.bar)</div><div>unittest {</div><div>//...</div>
<div>}</div><div><br></div><div>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.</div>
</div>