Elegant Documentation Never Lies
I was taking a close look at the API documentation of the ExtJS JavaScript library the other day and I noticed something very interesting.
You can see that the ExtJS folks have put out some great amounts of effort into documenting their API?s. The example shown here is from the Ajax ?class?. No big deal so far. But when you click on the name of a method (e.g. fireEvent), you get the following:
You?ll dive right into the source code! Interesting approach, don?t you think?
I mean, picture this: you?re looking at the documentation of NHibernate?s ISession interface. You click on the link for the Get method and it will take you right down to the source code for that particular version of NHibernate.
Wouldn?t this be cool for the documentation of the BCL as well? Or is it just me ? ?
Like .NET reflector but online?
Definitely, I event tend to use Reflector as a documentation reader!
Nitpicker corner: there is nothing interesting in signature of a method of the interface 😉 Probably you wanted to drill down to SessionImpl :>
@zproxy
@scooletz
Indeed like reflector, but built into the documentation (whether online or offline).
One might ask the question: “Isn’t it almost always a bad idea to expose internals?” whilst reasoning that the documentation should describe the contract of the method, what it does, but not how it does. Using the sourcecode in your documentation will almost certainly lead to users making assumptions about internals, which may change any time in the futures, so I think that this strategy of documentation has some potential to shackle and gag you. You change something and it breaks user code that relied on the internals. On the other hand: How is it different from coding in your IDE with all the framework sources installed and one mouse click away? It may be some effort to provide one doc for every version relaesed, even if it’s minor (for the user: he needs to point to the exact version he uses). But then again: How is it different from having it all wrapped together in your IDE, when the source is distributed with the release?
It’s convenient for the user, period.