At work we use NDoc 1.3 for all of our documentation needs. It’s a pretty good tool for the price. I was playing around with the options on an NDoc file and found that some of the default values for some settings aren’t the optimal ones. Here are some that you should change from the default to make your documentation better and your life easier:
- Set CleanIntermediates to True: this will delete the ndoc_msdn_temp folder after the chm has been created;
- Set AutoDocumentConstructors to False: if your constructor throws exceptions, say, which you document in the file, they will be missed if this is set to true;
- Set IncludeAssemblyVersion to True: this one is obvious and you may already be doing it;
- Set DocumentAttributes to True: this will output the attributes attached to the member in the syntax portion;
- Set DocumentProtectedInternalAsProtected to True: again, obvious; you don’t want to give away implementation details;
- Don’t EVER set DocumentExplicitInterfaceImplementations to True; NDoc barfs on that.
Depending on what release you are working on, you may want to set Preliminary to True. This will add “This documentation is preliminary and subject to change.” in red text to every page.
There’s a handy-dandy list of supported tags for NDoc that can be found here: http://ndoc.sourceforge.net/content/tags.htm
They support more than the ones supplied in the IDE for .NET 1.1 and it will make the docs look more like MSDN docs with very little effort on your part.
Also, an awesome tool that takes some of the drudgery out of documentation is GhostDoc. It’s an addin for VS and it’s free; right-click on a method or property and it will parse the name and figure out the proper summary for you. It’s pretty smart when it comes to inheritance documentation and the override methods for things like Object.Equals(). It’s a real time saver. And you can add your own. I’ve added some for BeginXxx and EndXxx methods among others.
One thing it doesn’t do is parse through the method to find Exceptions that are thrown. I’ve added some ReSharper templates to take most of the drudgery out of that task. I’ve found that I don’t throw very many crazy, custom exceptions; I use the standard ones that the framework provides which just beg for templated documentation: any ArgumentException and InvalidOperationException.
Now playing: Odds – Eat My Brain