Wednesday, February 13, 2008

XML Documentation C# Example

C# compiler can produce XML documentation for the comments added to the cs file.The comment added to the form should be inside one of these tags to get the documentation properly.

















Predefined TagUsed For
[To be encolosed in <>]
ca way to indicate that text within a description should be marked as code
codea way to indicate multiple lines as code
examplelets you specify an example of how to use a method or other library member
exceptionlets you document an exception class
includeyou refer to comments in another file, using XPath syntax, that describe
the types and members in your source code.
listUsed to insert a list into the documentation file
paraUsed to insert a paragraph into the documentation file
paramDescribes a parameter
paramrefgives you a way to indicate that a word is a parameter
permissionlets you document access permissions
remarkswhere you can specify overview information about the type
returnsdescribe the return value of a method
seelets you specify a link
seealsolets you specify the text that you might want to appear in a See Also section
summaryused for a general description
valuelets you describe a property



One example for such a cs file would be

///
<summary>
/// Public Base Form
///
</summary>
public partial class BaseForm : Form
{
/// <summary>
/// Constructor
///
</summary>
public BaseForm()
{
InitializeComponent();
}

.
.
.

/// <summary>
/// For invoking the reset button clicked event in the derived form
///
</summary>
/// <param name="sender"></param>
/// <param name="e"></param>
protected virtual void OnResetButtonClicked(object sender, EventArgs e)
{
}
#endregion
}

One drawback of this documentation is it requires comments for all the methods and events.Nothing can be missed or it keeps on throwing bugs.
Now take the project properties and under build tab,click on the XML Documentation File checkbox and the page now looks like,


Now build the project.In the bin\debug folder the xml file will be build.

Cheers!

No comments: