Getting From XML to MSDN-style Documentation
With the basic theory and the tags you'll need under your belt, you can now explore the tools to produce professional-looking documentation from your C# source code. As an example, Listing 1
shows a simple class documented with the XML tags shown in Table 1.
You can see that the XML tags reside within the triple-slash (///
) comment blocks. Note that if you're using Visual Studio .NET, as soon as you type ///
in front of a method or type, IntelliSense inserts the appropriate tagswell, really the most common. For example, here's what IntelliSense inserts when you type a triple-slash in front of the MyMethod
/// <param name="str"></param>
Note that Visual Studio inserts only the minimal
XML tags needed to document the method. That is, you should provide at least a description of the method (inside the
tag), a description of the method parameter (inside the
tag) and what the method returns (inside the
tag). Of course, you're free to insert other XML tags, such as <code>
, and so on. In fact, as Listing 1
shows, you can add other XML tags to enrich the resulting documentation.
That completes step 1 of the three main steps. The next step is to extract the XML comments to a file. If you're using Visual Studio .NET, there's an automated way to extract the XML comments to a file. First, create a new Console Application project, using the code in Listing 1
as the project's main class. To extract the XML tags to a file, follow these steps:
- Right click on the project in Solution Explorer and select Properties.
- Click on Configuration Properties and then select Build.
|Figure 2. Extracting XML Documentation: In Visual Studio, extracting XML comments requires only a few clicks and a file name entry.|
- Enter a name in the XML Documentation File field and click OK.
- Build the project by clicking on Build and selecting Build Solution.
shows the process, using the name DevXDocumentation.xml
for the file.
Notice that, by default, Visual Studio will save the XML file in the same folder as the assembly file created when you built the solution. In other words, if you accept the defaults, you'll find both the assembly and the XML file in the bin\Debug\
directory of your project. Listing 2
shows the extracted XML file.
In Listing 2
, you can see that VS .NET adds some tags and structure when it extracts the XML. Although you don't really need to care about VS .NET's additions to produce your professional documentation, it's not difficult to figure out what they mean. For example, in the attribute name of the element in Listing 2, M: stands for method and T: for type. If you're curious about the formatting details, you can refer to this XML Documentation Tutorial for further information.