Wednesday, November 12, 2008

Generating API Docs and the Relative Decline of MS developer tools

Three years ago, when I left the Microsoft/.NET development world for the wilds of J2EE/JEE and the confusing alphabet soup of standards, JSRs, JEE server implementations, etc.  I was expecting poorer quality development tools, much harder to configure servers, and a nightmare of database adminsitration and sub-standard drivers.   A couple months ago I returned to the MS world.  I thought it was just me having a hard time re-adjusting -- .NET 2.0 (and now 3.5) and C# 2.0 and 3.0 are more nuanced and complex than .NET 1.1 and C# used to be.   But I've had my off-on-the-road to Damascus (yes, I'm mixing references badly) moment. Microsoft is increasingly going to lose developers to Java and Ruby and other platforms and toolsets that are easier to use, cheaper (free as in beer) and far less proprietary in scope.

The catalyst for my epiphany was trying to generate some simple html API docs for a couple of our larger assemblies at work.  In Ruby or Java or Perl this is pretty simply done -- point a configuration task (i.e. in ant or maven or in code) at the project/module/package and very quickly voila, a set of JavaDoc based html documentation based on the structure of the code and the annotation comments on methods and classes.  In the last few versions of Eclipse you just select Project | Generate JavaDocs  and select a location and in a few SECONDS you get simple API docs in HTML that are easily added to source control, can be diffed, put on just about any sort of wiki or website, etc.

So how does Microsoft with their expensive Visual Studio and their proprietary advantage generate .NetDocs?  They don't.  To be fair there is the built in ability for compilation to generate XML documentation based on the /// comments in the code.  But there is NO built in mechanism to generate API docs.  With Visual Studio 2002 and 2003 there was an open source project called NDoc which generated html API from these comments and integretated into Visual Studio and ran fairly slowly.  But it is no longer maintained.  For .NET 2.0 and newer (3.0 and 3.5 and soon 4.0) there is an open source project from Microsoft called SandCastle.  It generates really good looking .chm (compiled HTML help) documentation but does NOT integrate at all with Visual Studio.  I couldn't get it working until an answer on pointed to a blog posting that ran me through it.  Even though it does generate HTML, it is really aimed at creating .chm files which are binary.  You have to run a separate tool outside of the IDE to create this documentation and it takes forever (this is because it has to actually connect to MSDN to get some .NET dependency documenation because the .NET core libraries are not open). So something that works quickly and is much easier to set up and use with a FREE IDE and is cross-platform is much harder to setup, doesn't work as usefully and is not integrated well with the EXPENSIVE proprietary tools from Microsoft.  

Yes API Docs are not very important in terms of overall development tools and functionality.  But this pattern is repeated throughout the Microsoft toolset (with the possible exception of SQL server -- the 2008 version of the Management Studio is incredible!) To get better (read useable) refactoring and getter/setter generation for Visual Studio (so you don't have to type lots of boiler plate code) developers in the know buy ReSharper.  Nothing wrong with that, it's a great tool BUT it galls me to buy an IDE then buy add-ins for it when you get the same functionality for free with Eclipse (and NetBeans and so on).  When MS developers realize that developers on other platforms have as good or better tools and they don't have to pay for them, no wonder they be less enthusiastic about MS.

I could keep ranting about the alphabet soup of extensions and versions and platforms from Microsoft but I won't.  MS has historically made the best tools for both rapid development and for robust Windows development, tools that were the envy of developers on other OS and platforms.  That's not true anymore and I think MS will pay the price in terms of lost developers.