Did you know you can write XML documentation for C#.NET projects as you write code? Documentation of software is critical not only for .NET applications but for all programs. Developers of .NET have the ability to minimize the task of writing documentation thanks to built-in xml documentation support.
In a nutshell, you can turn C# comments into .NET XML documentation with a simple change in Settings.
First let's establish the difference between regular .NET comments and XML comments. A regular comment is a quick bit of text that describes what a line of code does, for example:
int i = 10; //initialize variable
Boring right? While those comments are very useful, those are not helpful when building documentation for a component or application. Instead we want to use XML comments.
XML comments instead go right before a function. A simple example is:
/// <summary> /// This function is great /// </summary> private static int getInt()
Notice that .NET XML documentation comments start with 3 slashes instead of 2. These are the types of comments that are pure gold when it comes to documentation. Having more information on what a function does other than its name can be a huge time-saver. But the fun does not stop there, if you can parameters, you can add descriptions to each of them:
/// <summary> /// This function is great /// </summary> /// <param name="myInt">This is the input integer</param> private static int getInt(int myInt)
You can add XML descriptions for as many parameters as you want. Also know that you can apply comments to classes as well.
If you work with functions and classes that have XML documentation within your .NET project, you will notice that the documentation is immediately applied to IntelliSense. So if the C# XML documentation is more for the internal project, you can just sit back and enjoy the convenience.
But what if you want to export a library for example that will be used in further .NET development. Unfortunately XML comments are not automatically compiled with the assembly. You need to tell Visual Studio to generate a special file to store these comments.
For a given project, go to Project > [Project Name] Properties.... Then find the "Build" tab. Look near the bottom for the "XML documentation file" checkbox and check it. Go ahead and enter the name for the documentation file.
Once you have the XML file, you just have to make sure that it is in the same folder as the compiled assembly. Then other .NET developers will see the useful XML comments in their IntelliSense even though your library is compiled.
Having the entire documentation in a single file also gives you the flexibility to use other tools to create more sophisticated .NET XML documentation reading files.