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.
- 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?
I don't use Sandcastle as it doesn't solve the underlying problem: XML comments are hard to read and write.
ReplyDeleteI read code because I want the information in it. I read it like a newspaper or online article, which means I get impatient really fast if I can't quickly find what I need.
Imagine a newspaper article with lots of green text stuffed in between the content. How difficult wouldn't that be to read when you are constantly skipping sections while trying not to lose your current line of thought?
Combining that with a scrolling screen makes it only worse.
Not only does the reading experience suffer, but now I have two sources of information where the comments may very well be out of sync.
I can see the value of the XML comments when the source code is unavailable.
So if the documentation is most valuable when the source code is unavailable, and given that code is usually documented by technical writers after it's stable, why do we still insist on writing the documentation with the worst editor possible, and put it where it hurts the most?