INTERNET APPLICATION DEVELOPMENT
MID MARKET ERP DEVELOPMENT
Do you have to complete the application documentation once you complete your coding? It is possible with just a little effort in Visual Studio. Visual Studio builds in the XML documentation facility, even in the Express version. It is very easy to create a useful user guide.
Triple slash comment, is the key to embed XML within your codes. It tells the compiler the line starting with “///” contains XML. For example, you can add something at beginning of your method. After entering “///”, a summary tag is added automatically.
Next, you just simply add your explanation or thoughts on the method between the Summary tags.
Before generating your document, you need to make one change in the project properties: under the Build tab, check “XML documentation file.” It generates an XML file in the folder specified here.
Now, let’s build the application. MyDoc is generated in the folder.
It looks like this:
It not only shares your comments but also tells which method (member name) relate to your comments. However, this triple comment doesn’t work everywhere in your code. You only can add a comment to certain constructs: class, struct, enum, method, property, field indexer, delegate or event. Any triple slash comments not associated with one of these constructs is ignored by the compiler. Here is how you know if you put the comment in right place: if you start a triple slash comment in the wrong place, the IDE will not auto-generate a pair of <summary> tags for you. If you are in the correct place then the IDE generates a pair of tags, and also generates the name of the code construct and indicates its type with a leading letter followed by a colon. The first upper case letter “M:” in the member name indicates that the comment is related to a method. Here is the list for all letters.
• M: = Method
• N: = Namespace
• T: = Type i.e. class, interface, struct, enum or delegate
• F: = Field
• P: Property
• E: Event
• I: error unresolved construct
If I add a parameter “name” into the method sayHello(), it shows the IntelliSense for me to select the parameter tag when I am adding triple slash for parameter “name.”
Here is the updated XML file.
There are some more tags, like “example”and “remark,” you can select. It is also possible to structure the XML on your own. Then, you need to provide valid XML because the compiler will validate it.
Look for more on this in future blogs.