(About) 10 Steps Towards Documenting Your C# 2.0 Assemblies

Some time ago I used NDoc , a tool to "generate API documentation from .NET assemblies and XML documentation" . But how unfortunate is it that it does not work with Framework 2.0 nor are there plans to upgrade the tool (via).
Sandcastle to the rescue. After the SandCastle (*) installation is finished however, you won't find a shortcut in the Start menu. Turns out we have to do it all by hand. Allow me to save you half an hour of your life by offering these steps (for free!):

1. Go to the Sandcastle directory under \Program Files


2. Run MRefBuilder.exe on your assembly and see it spit out some XML, direct the output to an XML file


3. Offer the generated XML file to BuildAssember.exe. This will give you a nice error message
   Could not find file BuildAssembler.exe.config


4. Utter the words "Well, duh..." (that's what I did)


5. plug the message in Google and arrive at some information telling you about the Sandcastle Help File Builder so go there


6. Download and install the latest version. Fire it up and notice the remarkable resemblance with NDoc 1.3


7. Find an entry under Start and click it - (finding this is already candy at this time)


8. Open a documented assembly and finally build your first help file...
   > BUILD FAILED: De objectverwijzing is niet op een exemplaar van een object ingesteld
   In English: Object reference not set to an instance of an object


9. remember that you just switched from your virtual machine (b.t.w. once you've started to try all new software in a virtual machine first you'll never go back) back to the host and that probably Sandcastle Help File Builder will need Sandcastle itself for processing the assemby :-)
   > BUILD FAILED: Unable to find XML comments file: Unknown.xml. We need a comments file - edit build settings for your project in Visual Studio and ask for an XML documentation file


10. "Build the help file" / Control-Shift-B (they did have Visual Studio in mind here...). This can take a while so get some coffee.

Finally you'll find a .chm file which just begs to be opened, so help yourself. Notice that the .chm file works........ at least if you open it from your local hard drive. However, when you put it on a network drive to show it to someone else "the page cannot be displayed" pops up in the right pane. The index still works however. Must be something wrong with the reference to Framework documentation or something. But that's for another time.


11. realise that even help files are a world in itself

probably to be continued...

(*) I'm using the December CTP so these reflections might be different in your case