12,823,625 members (52,279 online)
alternative version

#### Stats

19.2K views
21 bookmarked
Posted 29 Jun 2009

# Using XML Documentation in your Code

, 29 Jun 2009 CPOL
 Rate this:
In this article, I will show you how to add documentation to your classes and methods to make good use of the IntelliSense feature and make your code more understandable

## Introduction

Many beginning and intermediate C# developers actually find out which exact method to use after reading the documentation about that method. For example, when I had just started network programming, I came to fully understand what an IPEndPoint was through that “description that was attached to the class and showed up in the Intellisense”.

Well, the technical word is “documentation”, and since it's done in XML as we shall see shortly, it is called XML documentation. What I am speaking of is illustrated in the diagram below:

## Getting Started

Without waiting, let’s get started. Create a simple console application, name it what you want—`XML_Doc` for example would be a good name. We shall keep our approach simple and work with some basic mathematics. So, add a class and call it `PhysicsLib`. You may just add what I have supplied with the code of the article so that you don't have to rewrite it. Alternatively, you may use your own class with your own implementation if you know what you are doing.

`PhysicsLib `contains definition of a function `getDistance() `which takes 1 overload. This is merely to calculate the distance travelled when a user inputs an initial velocity, acceleration and a final velocity or time in motion. It also contains some two constants (the speed of light in vacuum and characteristic impedance) and another class called `Conversions `to help us convert gallons to litres and Horsepower to Kilowatt.

The relevance of this article is to show how we can tell the user of our code what each method actually does and what each class contains, through the IntelliSense feature the way it is for all the inbuilt .NET functions.

There are two ways of doing this. One is to write the XML straight in the class file which we shall do briefly so that you get to understand exactly how this works. The second is simpler, a hell lot simpler. We shall use the class diagram, document the code from a table and let Visual Studio write the XML. (Don't get the IDE to always write the code for you when you can help it, it doesn't help much!)

We must differentiate strongly between the two ways we use classes in C# because this is of big importance also for XML documentation. One, we can choose to just add a class (*.cs) file to the project. Two, we can choose to import a precompiled class library (a DLL) and add it as a reference to the project, and invoke it with a `using `directive. If we chose the latter, as will be in many practical cases, we will need to generate the XML documentation file associated with the DLL, which is itself an XML file. If we just add a class to the code as we have done, then we won't need to generate this XML file. We shall study both ways.

In PhysicsLib.cs, just before the class declaration, insert three forward slashes `///`. It automatically adds some XML-like code as shown below:

```/// <summary>
/// Contains fundamental calculations, constants and conversions
/// </summary>```

The `<summary>` tags are used to hold data about classes and methods. For example, in this case, they say what `PhysicsLib `contains. With this, amazingly, you can already view some documentation if you try to declare a new `PhysicsLib `object. Just try to type phy… in the main program. You will see something like below:

## Further Points

Okay. Now we are getting somewhere. Let us continue. Inside, we have a method `getDistance()` as said earlier. It takes 3 parameters and we would like to document each of these. We will work only the first definition; the overload will be left for you to work with.

Now for the parameters, we document them by specifying parameter names within `<param>` tags. The description is what appears between the parameter tags as the value. It is standard XML, and is quite easy as shown below. Just type the three forward slashes before the `getDistance()` method you want to document. The following will appear:

```/// <summary>
/// INSERT DESCRIPTION HERE
/// </summary>
/// <param name="U"> INSERT DESCRIPTION HERE </param>
/// <param name="Acc"> INSERT DESCRIPTION HERE </param>
/// <param name="V"> INSERT DESCRIPTION HERE </param>```

Where the parameter name is “`U`” for example, we state that this is the initial velocity. The IDE automatically got for us all the available variables and did for us the XML. Your job is to just fill in your descriptions. We can now test our work. The image below shows mine. [Please note that for the `getDistance() `documentation to show on all the overloads, you must have it in summary tags appearing on all of them.]

## Inserting XML Documentation using the Class Diagram Viewer

This is an easier way of doing everything. We start the class diagram viewer  in the solution explorer and fill in the corresponding summary tables. It uses a tree hierarchy, which permits us to view all our classes, methods and variables. My class diagram looks like the one below:

When you click on any of the types available (method, constants or classes), witness that it opens up a table just below in which there is a summary column. This is the column in which you fill your documentation. It is so easy to see and do that I will not write much about it. Visual Studio will automatically add all the necessary XML for you and boom!  You are done!

## When Using a DLL

The procedure is a bit different when using a class library that has been precompiled and hence is going to be used as a reference in another application. This class MUST move with its documentation. The way this is done is simple, we set Visual studio to output our documentation as an XML. It is highly recommended that this file be stored in the same folder as the DLL because the IDE searches for it from there. Are you familiar with the phrase “the documentation is still being constructed. Please try again in a few seconds?” That happens when the IDE is still looping through the XML documentation file which the class/method/variable you are trying to access is associated with.

To set the IDE to output this XML file, you need to edit the build options. And set it to output this file in the location we want. Right click on the project file in the Solution Explorer. A window opens that looks like the one below:

Check the XML documentation checkbox and save changes to the project. When you build, the XML documentation file will be made at that time. You can now move with your library and your documentation as well. Enjoy!

## History

• 29th January, 2009: Initial post

## Share

 Engineer United Kingdom
I have deserted general software development and chosen to enter microprocessors and push around 1s and 0s

## You may also be interested in...

 Pro Pro

 First Prev Next
 No intellisense for a dll I refrenced in my project even though the dll is fully documented Rafique Sheikh26-Aug-10 11:22 Rafique Sheikh 26-Aug-10 11:22
 Re: No intellisense for a dll I refrenced in my project even though the dll is fully documented Maximus Byamukama29-Dec-10 5:58 Maximus Byamukama 29-Dec-10 5:58
 Re: No intellisense for a dll I refrenced in my project even though the dll is fully documented Rafique Sheikh29-Dec-10 11:36 Rafique Sheikh 29-Dec-10 11:36
 My vote of 2 PavanPareta29-Jun-09 20:01 PavanPareta 29-Jun-09 20:01
 Re: My vote of 2 Maximus Byamukama29-Jun-09 20:46 Maximus Byamukama 29-Jun-09 20:46
 Sandcastle TobiasP20-Jul-09 4:03 TobiasP 20-Jul-09 4:03
 Re: My vote of 5 kmlslm24-Sep-10 15:20 kmlslm 24-Sep-10 15:20
 Great article BigJim6129-Jun-09 14:36 BigJim61 29-Jun-09 14:36
 Re: Great article Maximus Byamukama15-Jul-09 2:33 Maximus Byamukama 15-Jul-09 2:33
 Last Visit: 31-Dec-99 19:00     Last Update: 27-Mar-17 10:37 Refresh 1