How to use XML document functionality in c#

The following example provides a basic overview of a archived type.

Example

// If compiling from the command line, compile with: -doc:

/// <summary>
/// Class level summary documentation goes here.
/// </summary>
/// <remarks>
/// Longer comments can be associated with a type or member through
/// the remarks tag.
/// </remarks>
public class TestClass : TestInterface
{
  /// <summary>
  /// Store for the Name property.
  /// </summary>
  private string _name = null;

  /// <summary>
  /// The class constructor.
  /// </summary>
  public TestClass()
  {
    // TODO: Add Constructor Logic here.
  }

  /// <summary>
  /// Name property.
  /// </summary>
  /// <value>
  /// A value tag is used to describe the property value.
  /// </value>
  public string Name
  {
    get
    {
      if (_name == null)
      {
        throw new ("Name is null");
      }
      return _name;
    }
  }

  /// <summary>
  /// Description for SomeMethod.
  /// </summary>
  /// <param name="s"> Parameter description for s goes here.</param>
  /// <seealso cref="">
  /// You can use the cref attribute on any tag to reference a type or member
  /// and the compiler will check that the reference exists.
  /// </seealso>
  public void SomeMethod(string s)
  {
  }

  /// <summary>
  /// Some other method.
  /// </summary>
  /// <returns>
  /// Return values are described through the returns tag.
  /// </returns>
  /// <seealso cref="SomeMethod(string)">
  /// Notice the use of the cref attribute to reference a specific method.
  /// </seealso>
  public int SomeOtherMethod()
  {
    return 0;
  }

  public int InterfaceMethod(int n)
  {
    return n * n;
  }

  /// <summary>
  /// The entry point for the application.
  /// </summary>
  /// <param name="args"> A list of command line arguments.</param>
  static int Main([] args)
  {
    // TODO: Add code to start application here.
    return 0;
  }
}

/// <summary>
/// Documentation that describes the interface goes here.
/// </summary>
/// <remarks>
/// Details about the interface go here.
/// </remarks>
interface TestInterface
{
  /// <summary>
  /// Documentation that describes the method goes here.
  /// </summary>
  /// <param name="n">
  /// Parameter n requires an integer argument.
  /// </param>
  /// <returns>
  /// The method returns an integer.
  /// </returns>
  int InterfaceMethod(int n);
}

This example generates a .xml file containing the following content.

<?xml version="1.0"?>
<doc>
  <assembly>
    <name>xmlsample</name>
  </assembly>
  <members>
    <member name="T:TestClass">
      <summary>
      Class level summary documentation goes here.
      </summary>
      <remarks>
      Longer comments can be associated with a type or member through
      the remarks tag.
      </remarks>
    </member>
    <member name="F:TestClass._name">
      <summary>
      Store for the Name property.
      </summary>
    </member>
    <member name="M:TestClass.#ctor">
      <summary>
      The class constructor.
      </summary>
    </member>
    <member name="P:">
      <summary>
      Name property.
      </summary>
      <value>
      A value tag is used to describe the property value.
      </value>
    </member>
    <member name="M:()">
      <summary>
      Description for SomeMethod.
      </summary>
      <param name="s"> Parameter description for s goes here.</param>
      <seealso cref="T:">
      You can use the cref attribute on any tag to reference a type or member
      and the compiler will check that the reference exists.
      </seealso>
    </member>
    <member name="M:">
      <summary>
      Some other method.
      </summary>
      <returns>
      Return values are described through the returns tag.
      </returns>
      <seealso cref="M:()">
      Notice the use of the cref attribute to reference a specific method.
      </seealso>
    </member>
    <member name="M:([])">
      <summary>
      The entry point for the application.
      </summary>
      <param name="args"> A list of command line arguments.</param>
    </member>
    <member name="T:TestInterface">
      <summary>
      Documentation that describes the interface goes here.
      </summary>
      <remarks>
      Details about the interface go here.
      </remarks>
    </member>
    <member name="M:(System.Int32)">
      <summary>
      Documentation that describes the method goes here.
      </summary>
      <param name="n">
      Parameter n requires an integer argument.
      </param>
      <returns>
      The method returns an integer.
      </returns>
    </member>
  </members>
</doc>

Compile the code

To compile the example, enter the following command:

csc /doc:

This command creates an XML file that can be viewed in the browser or using the TYPE command.

Reliable programming

The XML document begins with ///. When creating a new project, the wizard places lines starting with ///. There are some limitations when handling these comments:

1. The document must be in the correct format XML. If the XML format is incorrect, a warning is generated and the document file will contain a comment indicating that an error has been encountered.

2. Developers can create their own tag set at will. There is a set of recommended markers. Some recommended marks have special meanings:

The <param> tag is used to describe the parameters. If used, the compiler verifies that the parameter exists and that the documentation describes all parameters. If verification fails, the compiler will issue a warning.
The cref attribute can be attached to any tag to reference a code element. The compiler verifies that this code element exists. If verification fails, the compiler will issue a warning. The compiler considers all using statements when looking for types described in the cref attribute.
The <summary> tag is used by IntelliSense in Visual Studio to display additional information about a type or member.

Remark

The XML file does not provide complete information about the type and member (for example, it does not contain any type information). To get complete information about a type or member, use the document file with reflections to the actual type or member.

The above is the detailed content of how to use XML document functions in c#. For more information about using XML document functions in c#, please follow my other related articles!