Generating Help File in C#

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

{

///

/// The main entry point for the application.

/// Developed By : C# Team

/// Developed On : 21 Oct,07

///


[ 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




Program




The main entry point for the application.
Developed By : C# Team
Developed On : 21 Oct,07







Note: -Main portion of XML documentation is found in element: This element contains one tag for each documented item in the source code. The 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. “name" = Attribute Prefixes >



Other Important Tags:



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


1. :- 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 Main () function for the /// Program class.

2. :- Tag to indicate that multiple lines of text in your comments should be treated as code: E.g.

///

/// Argument[0]: command line argument 1

/// Argument[1]: command line argument 2

/// Argument[2]: command line argument 3

///


3. :- You can use the tag to document any exceptions that may be raised from the member's code. The 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.

///

/// Raised if the input is less than 0.

///


4. :- Use the 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 tag to document the availability of your code and data. The 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.

///

/// Everyone can access Main ().

///


5. :- Use the tag to add information about an item. The element is great for providing an overview of a method or variable and its usage. The tag carries no attributes and its text contains the remarks: E.g.

///

/// The Main () function is the entry point into the

/// application. The CLR will call Main () to start

/// the application after the application loads

///


Comments



  • Do not include your name, "with regards" etc in the comment. Write detailed comment, relevant to the topic.
  • No HTML formatting and links to other web sites are allowed.
  • This is a strictly moderated site. Absolutely no spam allowed.
  • Name:
    Email: