How to create documentation from comments in .Net?

Psmiles18
Posted by in VB.NET category on for Beginner level | Views : 19557 red flag
Rating: 5 out of 5  
 4 vote(s)

This article is useful to generate XML document from XML comments written in VB .Net / C# .Net code

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 :)

Page copy protected against web site content infringement by Copyscape

About the Author

Psmiles18
Full Name: Payal Desai
Member Level: Starter
Member Status: Member
Member Since: 5/7/2010 5:28:43 AM
Country: India



Login to vote for this post.

Comments or Responses

Posted by: Vuyiswamb on: 6/18/2010
Good Article, keep up the Good Work
Posted by: Hitesh.dil on: 6/23/2010
Hello Payal,

I am getting the following error:
<MyPage>.cs(28,17): error CS0234: The type or namespace name 'Security' does not exist in the namespace 'Microsoft' (are you missing an assembly reference?)

I am using Microsoft.Security.Application in cs page, and also i have already added web reference of AntiXssLibrary.dll
But its not coming any error when i build my project. It only raised when use

csc MyPage.cs /doc:MyCS.xml

in vs2005 command prompt.
Posted by: Hitesh.dil on: 6/23/2010
Its Solved Now Thanks.

Good Article.

If you want to create xml doc for all the .cs pages in the respective project no need to use this:

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

only build the project and here (/bin) you will get that.

Thanks
Posted by: Psmiles18 on: 6/23/2010
ok Hitesh, thanks your suggestion, i will try that way too :)

Login to post response

Comment using Facebook(Author doesn't get notification)