C# supports 3 types of comments in source code:
1. //
2. /* */
3. ///
If you are from C++ background, probably you are familiar with the
first two, but the third one is new. Let us analyze each type.
The first one ( // ) is used to comment a single line. Anything after
the // is a comment and compiler will ignore it.
Example :
string name = "John"; // This variable represents a name.
The second type of comment can be used to comment multiple lines.
Example:
/* The following code snippet saves the values
into database.
If the Save() operation fails, it will throw an exception.
*/
public void Save()
{
...
}
And the last one is the most interesting ( /// ). It helps you build a
documentation for your entire C# project. This type of comment is called 'XML Comments', because it helps
generate XML documentation from these comments. Also, VS.Net has
some built in features to auto complete this type of comment. Let us
see what make this type of commenting different from others
and how you can use them to build documentation.
Create a new C# class library project using VS.Net. it will create a
default class called 'Class1' for you. Just replace the
contents of this class with the following code :
public class Sample
{
}
Now let us add the XML comment by typing /// just before the class declaration. When you type /// above the class
declaration, Intellisense automatically adds the <summary> tags. See the code below:
/// <summary>
///
/// </summary>
public class Sample
{
}
Now you can type a summary of your class between the <summary> tags.
/// <summary>
/// This is a sample class which demonstrates the XML Comment feature.
/// </summary>
public class Sample
{
}
Add a method called 'SaveValues(...)' as shown below:
/// <summary>
/// This is a sample class which demonstrates the XML Comment feature.
/// </summary>
public class Sample
{
public bool SaveValues ( string name, int age )
{
return true;
}
}
Now type /// just above the method name. VS.net inserts few XML tags automatically.
/// <summary>
/// This is a sample class which demonstrates the XML Comment feature.
/// </summary>
public class Sample
{
/// <summary>
///
/// </summary>
/// <param name="name"></param>
/// <param name="age"></param>
/// <returns></returns>
public bool SaveValues ( string name, int age )
{
return true;
}
}
For each parameter of the method, VS.net creates a <param> tag. You can insert a brief description for each parameter of your method.
/// <summary>
/// This is a sample class which demonstrates the XML Comment feature.
/// </summary>
public class Sample
{
/// <summary>
/// This method saves the name and age into the database.
/// </summary>
/// <param name="name">'Name' of employee to be saved.</param>
/// <param name="age">'Age' of employee to be saved.</param>
/// <returns>True if save is success, False if save fails.</returns>
public bool SaveValues ( string name, int age )
{
return true;
}
}
Once you have completed the above steps, you can build the documentation. VS.Net comes with a handy tool for this.
Go to Tools menu and select Build Comment Web Pages....
This will build a beautiful set of web pages for you with proper navigation between pages. All your classes
will be documented with proper description (whatever you specified in the /// comments. You can use this set of html pages
as your product documentation. The documentation look complete in itself and you can navigate between classes following the hyperlinks.
|
No responses found. Be the first to respond and make money from revenue sharing program.
|