An interesting feature of the C# compiler is to generate XML documentation from the comments. C# compiler reads specially formatted comments and generates XML documentation from the comments. You can then displays this XML on the Web to provide an extra level of documentation to developers who need to understand the structure of your applications.

Pre-requisites to generate XML documentation from the comments are:

• Use three slashes for comments(///). The C# compiler does not generate any XML Documentation for any comments that do not begin with three slashes. Nor does the C# compiler generates any XML documentation for regular, multi line, comments.


• Use the /doc option of the C# compiler to specify the name of the file that should contain the generated XML documentation.

Example: Demonstrate XML documentation from Comments

Step1: In the first step we create the C# code file.

using System;

using System.Collections.Generic;

using System.Windows.Forms;

namespace _CSharpApplication

{

  static class Program

    {

    /// <summary>

    /// The main entry point for the application.

    /// Developed By : C# Team

    /// Developed On : 21 Oct,07

    /// </summary>

    [ STAThread ]

    static void Main ()

        {

        Application .EnableVisualStyles();

        Application .SetCompatibleTextRenderingDefault( false );

                System.Console.WriteLine( "StartUp for C# World!" );

        }

    }

}

Step2: The following command is used to generate the help file. The command will create two files i.e. “Program.exe” and other is “ProgramHelpFile.xml” .

Command: csc /doc: HelpFile.xml ProgramFile.cs

Output:-

The following xml will be generated by the above command.

ProgramHelpFile.xml

<?xml version="1.0"?>

<doc>

    <assembly>

        <name>Program</name>

    </assembly>

    <members>

        <member name="M:_CSharpApplication.Program.Main">

            <summary>

            The main entry point for the application.

            Developed By : C# Team

            Developed On : 21 Oct,07

            </summary>

        </member>

    </members>

</doc>

Note: -Main portion of XML documentation is found in <member> element: This element contains one <member> tag for each documented item in the source code. The <member> tag contains one attribute, name, which names the member being documented. The value of the name attribute starts with a one-letter prefix describing the type of information being described. Options for the first letter of the name attribute's value and its meaning. <member> “name” = Attribute Prefixes >

Other Important Tags:

The following is the list of more help file tags which can be used in the C#.

1. <c>:- T ag to indicate that a small part of your comment should be treated as code. Style sheets may use this element to display the code portion of your comment E.g. /// This is the <c> Main ()</c> function for the /// Program class.


2. <code>:- Tag to indicate that multiple lines of text in your comments should be treated as code: E.g.
   /// <code>
   /// Argument[0]: command line argument 1
   /// Argument[1]: command line argument 2
   /// Argument[2]: command line argument 3
   /// </code>


3. <exception>:- You can use the <exception> tag to document any exceptions that may be raised from the member's code. The <exception> tag must contain an attribute called cref whose value specifies the type of exception being documented. The cref attribute value must be enclosed in quotes. The text of the element describes the conditions under which the exception is thrown: E.g.
   /// <exception cref="System.Exception">
   /// Raised if the input is less than 0.
   /// </exception>


4. <permission>:- Use the <permission> tag to document the permissions available on a given function or variable. Access to a class's code and data can mean access to all of the code or it can be restricted to a certain subset of code. You can use the <permission> tag to document the availability of your code and data. The <permission> tag makes use of one attribute: cref. The value of the cref element must name the function or variable whose permissions are being documented: E.g.
   /// <permission name="Main()">
   /// Everyone can access Main ().
   /// </permission>


5. <remarks>:- Use the <remarks> tag to add information about an item. The <remarks> element is great for providing an overview of a method or variable and its usage. The <remarks> tag carries no attributes and its text contains the remarks: E.g.
   /// <remarks>
   /// The Main () function is the entry point into the
   /// application. The CLR will call Main () to start
   /// the application after the application loads
   /// </remarks>