How to create documentation from comments in .Net?

Introduction

Comments in code are not just helpful to increase the readability, but they also provide the way to create document. To create document you cannot use single-line (' for VB .Net or // for C# .Net) or multi-line comments(/* */). YOU HAVE TO USE XML DOCUMENTATION COMMENTS, which are written as 3 apostrophe(''') in VB .Net and 3 forward slash(///) in C# .Net. Lets see how its possible.

Writing comments for documentation

[NOTE : Documentation comments cannot be applied to Namespaces. The reason is that one Namespace can span several assemblies, and not all assemblies have to be loaded at the same time.]

IN VISUAL BASIC PROJECT :

Add new project > Visual Basic > Web > ASP .Net Web application > Project > <PROJECT_NAME> Properties > Compile tab > Check ‘Generate XML Documentation file’.
This will generate XML file in the /bin folder, where your project resides
(Same procedure For Windows application)

IN C# PROJECT :

Add new project > Other languages > Visual C# > Web > ASP .Net Web application > Project > <PROJECT_NAME> Properties > Build tab > Output section > Check ‘XML Documentation file’, give path & name as per the requirement
(Same procedure For Windows application)

IN C# WEBSITE :

Go to visual studio 2005/2008 command prompt > go to path/directory where your project resides > type following command & hit enter :

csc Default.aspx.cs /doc:MyCS.xml

[NOTE : CSC is the C# compiler]

This will generate XML file in that folder itself, output file is as shown below in Output section.

Partial Public Class _Default
    Inherits System.Web.UI.Page
 
 
    ''' <summary>
    ''' this is page load event
    ''' </summary>
    ''' <param name="sender"></param>
    ''' <param name="e"></param>
    ''' <remarks></remarks>
    Protected Sub Page_Load(ByVal sender As Object,ByVal e As System.EventArgs) Handles Me.Load
        HelloEg()
    End Sub
 
    ''' <summary>
    ''' this is hello eg
    ''' </summary>
    ''' <remarks></remarks>
    Protected Sub HelloEg()
        Response.Write("Hi")
    End Sub
 
    ''' <summary>
    ''' this is not called method
    ''' </summary>
    ''' <param name="i"></param>
    ''' <param name="s"></param>
    ''' <remarks></remarks>
    Protected Sub NotCalled(ByVal i, Optional ByVal s = 0)
    End Sub
 
    ''' <summary>
    ''' this is unload event
    ''' </summary>
    ''' <remarks></remarks>
    Protected Sub Page_Unload(ByVal sender As Object,ByVal e As System.EventArgs) Handles Me.Load
        Response.Write("Hi unload event")
    End Sub
 
End Class

Whatever parameters our methods have, it will be automatically added as XML comments above the method.

In the above code, i have written 1 method - Sub NotCalled. This is to show that even if there is no call to this method, it will be included in the documentation. So you can also get the clear & quick view of unused method(s) in your code.

Output:

Following will be the generated XML documentation :

<?xml version="1.0" ?>
<doc>
<assembly>
<name>RnDProject2008</name>
</assembly>
<members>
<member name="F:RnDProject2008._Default.form1">
<summary>form1 control.</summary>
<remarks>
Auto-generated field. To modify move field declaration from designer
file to code-behind file.
</remarks>
</member>
<member name="M:RnDProject2008._Default.Page_Load(System.Object,System.EventArgs)">
<summary>this is page load event</summary>
<param name="sender" />
<param name="e" />
<remarks />
</member>
<member name="M:RnDProject2008._Default.HelloEg">
<summary>this is hello eg</summary>
<remarks />
</member>
<member name="M:RnDProject2008._Default.NotCalled(System.Object)">
<summary>this is not called comment</summary>
<param name="s" />
<remarks />
</member>
<member name="M:RnDProject2008._Default.Page_Unload(System.Object,System.EventArgs)">
<summary>this is unload event</summary>
<remarks />
</member>
</members>
</doc>

Conclusion

Hope this clarifies your problems / doubts related to documentation in .Net. Please respond back, in case of any queries / suggestions. Thank you :)