About a month ago, I began using the October 2007 CTP release of Sandcastle, Microsoft’s offering for generating code documentation files from existing .NET 2.0 assemblies. The product will no doubt become the standard for generating your project’s docs, replacing the previously ubiquitous NDoc (which is no longer supported, partly due to personal attacks directed towards chief dev Kevin Downs. What a nice way to support his volunteer efforts, huh?). Along the way I’ll try to absolutely mangle a boxing metaphor… Here we go:
Round One: Me vs. The ‘Castle Command Line
Carmen my love.. I dance so sweet for you!
My first encounter with Sandcastle was a knockdown, drag out tussle with lack of documentation and the joys of the command line, but I stuck it out in honor of our comrades from the 1980′s and beyond… sarcasm aside, I was pleasantly surprised by the output of the tool. The docs were professional looking, and with some love could have been presentable to our clients if needed. (I was only looking to generate some docs to give our dev team an easy to way see how our previous committment to full code documentation was shaping up)
Decision: It was easy to tell this was going to become a powerful tool in the near future, but was still on the undercard with the hairy 300lb guy they pulled out of a bar… or maybe that’s just the Cedar Rapids circuit?
Round Two: Introducing the Sandcastle Help File Builder
Would you like some punch to drink? Ha Ha Ha!
Once my team decided we needed a complete snapshot of our code-level XML documentation, I was thinking of the best way to create one help file for all assemblies,that included our custom comments and offered the functionality and usability NDoc had provided for so long,all without the painful command line monotony I envisioned. Lo and behold, Eric Woodruff’s NDoc-style GUI appeared. Yes, I see the irony of Microsoft trumping an open source project with it’s own offering, only to have a UI created that is a mimic of the original…. but hey, what works, lives.
The GUI tool relies on the Sandcastle 2007 October CTP, the HTML Help Workshop for building HTML help files, and the HTML Help 2.0 compiler just as the command line utilities do, but wraps all this in a clean, intuitive interface. I simple enabled our projects to produce XML document outputs (via the Project Property –> Build tab), and referenced these output files using the UI tool. It took about 40 minutes for the help documents to compile, but afterwards we had a web site and generated help docs for our team to review for missing comments. The web site is slow and clunky, but I’ve got a little man-crush going with the .chm. Puppy love I guess. And imagine the help a full .chm file could be to an incoming team member. At some point this will become a client-worthy offering that a lot of consultants may not take the time to produce, so this tool has become a nice value-add in my .NET toolbelt.
Decision: Sancastle with the CodePlex GUI are prepped for the spotlight, stay tuned to see how these products evolve.
Round Three: Gratuitous Bald Bull
My barber didn’t know when to quit… Do you?
Okay, okay, I’m done… calm down.
Must-have Mike Tyson Punch Out references: http://en.wikipedia.org/wiki/Little_Mac#Little_Mac






