C# XML Documentation

In this chapter you will learn:

  1. What is XML Documentation
  2. Syntax to use XML document
  3. XML Documentation Standard Tag
  4. Example
  5. see also and reference

Description

A documentation comment is a piece of embedded XML that documents a type or member.

Syntax

A documentation comment comes immediately before a type or member declaration, and starts with three slashes:


/// <summary>Cancels a running query.</summary>
public void Cancel() { ... }

Multiline comments can be done either like this:


/// <summary>
/// Cancels a running query
/// </summary>
public void Cancel() { ... }

or like this (notice the extra star at the start):


/**
   <summary> Cancels a running query. </summary>
*/
public void Cancel() { ... }

Standard Tag

Here are the standard XML tags that Visual Studio and documentation generators recognize:


<summary>...</summary>                        A single phrase or sentence summary.
<remarks>...</remarks>                        Additional text that describes the type or member.
<param name="name">...</param>                Explains a parameter on a method.
<returns>...</returns>                        Explains the return value for a method.
<exception [cref="type"]>...</exception>      Lists an exception that a method may throw.
<permission [cref="type"]>...</permission>    Indicates an IPermission type required by the documented  type or member.
<example>...</example>                        Denotes an example.
<c>...</c>                                    Indicates an inline code snippet.
<code>...</code>                              Indicates a multiline code sample.
<see cref="member">...</see>                  Inserts an inline cross-reference to another type or member.
<seealso cref="member">...</seealso>          Cross-references another type or member.
<paramref name="name"/>                          References a parameter from within a <summary> or <remarks> tag.
<list type=[ bullet | number | table ]>          Instructs documentation generators to emit a bulleted, numbered, or table-style list.
  <listheader>/*  w  ww .  j  ava 2 s  . co  m*/
    <term>...</term>
    <description>...</description>
  </listheader>
  <item>
        <term>...</term>
       <description>...</description>
  </item>
</list>
<para>...</para>                                 Format  the  contents  into  a  separate paragraph.
<include>                                        Merges an external XML file that contains documentation.

Example


using System;//from w w w  .  j av  a  2 s. com

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

    }
}

If you compile with the /doc directive, the compiler extracts and collates documentation comments into a single XML file.

Example 2


using System;/*from w  w w  .  j ava2  s  .  c  om*/

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

Next chapter...

What you will learn in the next chapter:

  1. Predefined types in C#
  2. Predefined types alias
Home »
  C# Tutorial »
    C# Language »
      C# Statements
C# Comments
C# if statement
C# while loop
C# do while loop
C# for loops
C# foreach statement
C# switch statement
C# break statement
C# continue statement
C# goto statement
C# XML Documentation