On Mon, Jan 24, 2011 at 3:43 PM, Andrei Alexandrescu < seewebsiteforem...@erdani.org> wrote:
> On 1/24/11 3:36 PM, Steven Schveighoffer wrote: > >> On Mon, 24 Jan 2011 16:03:24 -0500, Andrei Alexandrescu >> <seewebsiteforem...@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.