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:
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> 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:
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:
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!
- 29th January, 2009: Initial post