Just because summer is over, it doesn’t mean we still can’t play in the sand… Sandcastle that is. Here’s a 26 page article on doing just that…

simple-talk - Taming Sandcastle: A .NET Programmer's Guide to Documenting Your Code

“The most effective way to document .NET code so that others can understand it and use it, is to use XML Documentation and Sandcastle. It isn't that easy. Michael Sirens produces the easy guide to the process that Microsoft never managed, and introduces several applications that help.

Contents

• XML Documentation Comments: First Look.
• Doc-Comment Elements.
• Automate Your Doc-Comment Creation.
  • Level 1: Word-level Assist: Intelligence.
  • Level 2: Foundation-laying Assist: Smart Comment Editing.
  • Level 3: Supercharged Assist: GhostDoc.
• The Problem of Documentation Generation.
• Sandcastle Help File Builder
• Running Sandcastle Help File Builder
• Sandcastle Help File Builder Configuration: First Look.
• Rules for Embedding HTML..
• Sandcastle for NDoc Users.
• Sandcastle Considerations.
  • Browser Flexibility.
  • Storage Requirements.
  • Performance and Inheritance.
  • Issues Deploying on Linux/Unix.
  • Disambiguating and Resolving <see> References.
  • Verbosity of <see> Elements.
  • Referencing Generic Types in <see> Elements.
  • Displaying Sample Code.
  • Style Choices and Code Display Issues.
  • Using Favicons in Your Generated Web Site.
  • Rendering Issue with Unresolved Links.
  • File Naming Conventions.
  • Specifying Debug or Release Configuration.
  • Finding What You Missed.
  • Documenting Namespaces.
• Conclusion.

---

Imagine it: You’ve spent months developing your new .NET application. At some point, you want to take an action within your application whenever files in a certain directory are changed by another process external to your program. You think about coding this “directory watcher” from scratch but, just as you are about to get started with the design, you come across the System.IO.FileSystemWatcher class. The hyperlink I have attached to that class name takes you to one entry point into the vast MSDN documentation collection for the API of .NET itself. The FileSystemWatcher does just what you need. Yet another building block from .NET now saves you substantial time, money, and effort towards reaching your goal. But having the building block is only half the story—the information on how to use it—the API—is the other half. If that  comprehensive MSDN documentation  wasn’t there to provide usage details, then most of you would find ways to cope: You might, for example, fire up .NET Reflector, examine class and method signatures or do some experimentation. Essentially what you would be doing—whether you write it down or not—is “documenting” the API for your own needs. Now, if you multiply the time you spend doing so by hundreds or thousands of other developers duplicate your effort, you’ll understand the scale of the wasted time. Because Microsoft took the time and effort to create and publish the API for all of the .NET libraries, this saves a huge amount of man-hours of work for you and other .NET developers. You want to extend the same courtesy to your potential user community, or fellow team-members. 

…

 

…”

It’s been a long time since I’ve blogged about Sandcastle and when I saw this very cool article, I knew I had to highlight it… But I also have to wonder at the future of Sandcastle. But I guess that since it uses the VS “native” XML code comments, even if it dies, the effort invested in viable code commenting wouldn’t be wasted.

 

Related Past Post XRef:
.Net Code Contracts + XML Comments = (as good as) peanut butter and chocolate?

Visual Studio 2005 SDK version 4.0 Released