Problem solve Get help with specific problems with your technologies, process and projects.

Creating online documentation

C# allows automatic generation of comments in XML format.

Please let other users know how useful this tip is by rating it below. Got a tip or code of your own you'd like to share? Submit it here!


C# allows automatic generation of comments in XML format. XML is similar to HTML. Let's concentrate on C#. Note that all programs in this lessons need to be compiled with the option /doc. For example, if you save the program below in a file hello.cs and want to generate hello.xml, you would type csc /doc:hello.xml hello.cs. To generate an XML file from a C# program, we add triple slash comments ///. The simplest comment starts with a keyword <summary> and ends with a keyword </summary>. Comments should be placed just before the line of code they are annotating.

//This is just a comment 
using System; 
///<summary> class Test has only one method </summary> 
class Test 
{ 
    ///<summary> string z contains identifier to output </summary> 
    private static string z="Hello"; 
    ///&lsummary> method Main is an entry point of the program </summary> 
    public static void Main() 
    { 
    Console.WriteLine(z); 
    } 
}  

Let's look inside hello.xml, which captures the general structure of the program hello.cs. Here is a small dictionary:

T    Type. Class Test is a type. 
 
F    Class member. z is a data member of class Test. 
 
M    Method. Main is a method of class Test. 
 
!    Error. Dead link. 

P    Property.

<?xml version="1.0" ?>

<doc>
<assembly>
  <name>cs</name> 
  </assembly>
  <members>
  <member name="T:Test">
  <summary>class Test has only one method</summary> 
  </member>
  <member name="F:Test.z">
  <summary>string z contains identifier to output</summary> 
  </member>
  <member name="M:Test.Main">
  <summary>method Main is an entry point of the program</summary>
  </member>
  </members>
</doc>

Other interesting commands are:

  • <see also cref= "Something"/> gives a link to Something, which must be in your program file. <para> and </para> mark the begining and the end of the paragraph.

  • <remarks> </remarks> -- similar to <summary>


    Source: DotNetExtreme.com
  • This was last published in March 2003

    Dig Deeper on .NET Framework development with XML and XAML

    Start the conversation

    Send me notifications when other members comment.

    Please create a username to comment.

    -ADS BY GOOGLE

    SearchCloudComputing

    SearchSoftwareQuality

    TheServerSide.com

    SearchCloudApplications

    Close