Csharp/CSharp Tutorial/Language Basics/Documentation Comments

Compiler Support Tags

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;
    }
}

Documentation Comments for A member variable

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;
    }
}

Documentation Comments for a method with parameters

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;
        }
    }
}

Documentation Comments for A property

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;
            }
        }
    }
}

Documentation Comments for class

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

Documentation Comments for Main function

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)
        {
        }

    }
}

Recommended Code Comment XML Elements

Predefined XML Element            Meaning in Life
<c>                               code font
<code>                            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

XML Documentation

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.