Csharp/CSharp Tutorial/Language Basics/Documentation Comments

Compiler Support Tags

<source lang="csharp">using System; namespace Payroll {

   /// <summary> 
   /// Document for Employee class
   /// See a cross reference <see cref="String">string</see>
   /// </summary>
   public class Employee
   {
       /// <summary>
       /// Comment for the constructor
       /// <paramref name="name">name2</paramref> is a string.
       /// </summary>
       /// <param name="id">Employee id number</param>
       /// <param name="name">Employee Name</param>
       public Employee(int id, string name)
       {
           this.id = id;
           this.name = name;
       }
       
       /// <summary>
       /// Comments for another constructor
       /// </summary>
       /// <remarks>
       /// <seealso cref="Employee(int, string)">Employee(int, string)</seealso>
       /// </remarks>
       public Employee()
       {
           id = -1;
           name = null;
       }
       int id;
       string name;
   }

}</source>

Documentation Comments for A member variable

<source lang="csharp">using System; namespace DocumentationCommentsExample {

   /// <summary>
   /// A documentation sample - the short description goes here
   /// </summary>
   /// <remarks>Where a longer description would go</remarks>
   class ClassExample
   {
       /// <summary>
       /// A member variable
       /// </summary>
       private string m_str;
   }

}</source>

Documentation Comments for a method with parameters

<source lang="csharp">using System; namespace DocumentationCommentsExample {

   /// <summary>
   /// A documentation sample - the short description goes here
   /// </summary>
   /// <remarks>Where a longer description would go</remarks>
   class ClassExample
   {
       /// <summary>
       /// A member variable
       /// </summary>
       private string m_str;

       /// <summary>
       /// A method example
       /// </summary>
       /// <param name="val">a new value to be saved</param>
       /// <returns>the length of the string</returns>
       public int MethodExample( string val )
       {
           m_str = val;
           return val.Length;
       }
   }

}</source>

Documentation Comments for A property

<source lang="csharp">using System; namespace DocumentationCommentsExample {

   /// <summary>
   /// A documentation sample - the short description goes here
   /// </summary>
   /// <remarks>Where a longer description would go</remarks>
   class ClassExample
   {
       /// <summary>
       /// A member variable
       /// </summary>
       private string m_str;

       /// <summary>
       /// A property example
       /// </summary>
       /// <remarks>
       /// You would put a more in depth description inside remarks tags
       /// </remarks>
       public string PropertyExample
       {
           get
           {
               return m_str;
           }
       }
   }

}</source>

Documentation Comments for class

<source lang="csharp">using System; namespace DocumentationCommentsExample {

   /// <summary>
   /// A documentation sample - the short description goes here
   /// </summary>
   /// <remarks>Where a longer description would go</remarks>
   class ClassExample
   {
   }

}</source>

Documentation Comments for Main function

<source lang="csharp">using System; namespace DocumentationCommentsExample {

   /// <summary>
   /// A documentation sample - the short description goes here
   /// </summary>
   /// <remarks>Where a longer description would go</remarks>
   class ClassExample
   {
       /// <summary>
       /// The main method for the program
       /// </summary>
       /// <param name="args">command line arguments</param>
       static void Main(string[] args)
       {
       }

   }

}</source>

Recommended Code Comment XML Elements

<source lang="csharp">Predefined XML Element Meaning in Life <c> code font Indicates multiple lines should be marked as code <example> Mocks up a code example <exception> Documents which exceptions a given class may throw <list> Inserts a list or table into the documentation file <param> Describes a given parameter <paramref> Associates a given XML tag with a specific parameter <permission> Documents the security constraints for a given member <remarks> Builds a description for a given member <returns> Documents the return value of the member <see> Cross-references related items in the document <seealso> Builds an "also see" section within a description <summary> Documents the "executive summary" for a given member <value> Documents a given property</source>

XML Documentation

<source lang="csharp">Tag Description <c> Marks up text within a line as code, for example: <c>int i = 10;</c> <code> Marks multiple lines as code. <example> Marks up a code example. <exception> Documents an exception class. (Syntax verified by the compiler.) <include> Includes comments from another documentation file. (Syntax verified by the compiler.) <list> Inserts a list into the documentation. <param> Marks up a method parameter. (Syntax verified by the compiler.) <paramref> Indicates that a word is a method parameter. (Syntax verified by the compiler.) <permission> Documents access to a member. (Syntax verified by the compiler.) <remarks> Adds a description for a member. <returns> Documents the return value for a method. <see> Provides a cross-reference to another parameter. (Syntax verified by the compiler.) <seealso> Provides a "see also" section in a description. (Syntax verified by the compiler.) <summary> Provides a short summary of a type or member. <value> Describes a property.</source>