Chapter 9. Generating documentation
This chapter covers
- Using XML documentation tags to comment code
- Creating rich technical documentation with Sandcastle
Every developer knows another developer who doesn’t like to write documentation. Most of them see this fellow developer every day morning in the mirror; some see the other developer a little later, in the office. Even if you’re in the second group, you probably wouldn’t mind a little help on the documentation side, right?
There’s no magical way to produce documentation. It has to be written. But you can do this the smart way. How about documenting your code inside your source files and generating the documentation from there? You can do so by adding special XML comments to the code. The specially formatted tags, which you’ll learn to use in this chapter, are extracted during the build to a separate XML file. An external tool called Sandcastle can take this file and transform it into nice-looking technical documentation. Figure 9.1 illustrates the process.
In this chapter, we’ll look at how to document your code using XML notation. To do this, you’ll use Sandcastle to generate an HTML and Compiled HTML Help (CHM) format documentation. Then you’ll integrate everything into your CI process.
Figure 9.1. Generating documentation: from source code to XML, and finally to technical documentation
A normal comment in C# looks like this
or like this