Recently it seems that API references have gone out of fashion. I'm guessing VS.NET IntelliSense might explain the lack of interest? Well, IntelliSense is no good for lengthy explanations. And so far nobody has cared enough about IntelliSense to implement it for C# and Emacs.
So I'm going to keep on publishing API ref pages for the free software I write.
BTW, I eventually found an NHibernate API ref.
Horse : Content :: Carriage : Ads
56 minutes ago
Similarly annoying is the "API references offered up in place of documentation" cop out. MsBuild Community Tasks comes to mind. The only docs I've been able to find are help files generated from code comment xml. It requires one to parse and differentiate the intermingled task developer info from msbuild script developer info. Info for task consumers is quite different and ought to be separate from info for task creators.
ReplyDelete> Info for task consumers is quite different and ought to be separate from info for task creators.
ReplyDeleteI agree with you there, Josh.
I toyed with the idea of extracting online help for iDeal from doc comments, partly because it seems that doc comments are less likely to go stale than a document separate from code. But even summary contents were often inappropriately technical.
I think my favorite manual is still the http://svnbook.red-bean.com/. As far as I know it's maintained by shear discipline (or joy) rather than by any unusually effective technique.