c#如何使用 XML 文档功能

下面的示例提供对某个已存档类型的基本概述。

示例

// if compiling from the command line, compile with: -doc:yourfilename.xml

/// <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 system.exception("name is null");
      }
      return _name;
    }
  }

  /// <summary>
  /// description for somemethod.
  /// </summary>
  /// <param name="s"> parameter description for s goes here.</param>
  /// <seealso cref="system.string">
  /// 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(system.string[] 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);
}

该示例生成一个包含以下内容的 .xml 文件。

<?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:testclass.name">
      <summary>
      name property.
      </summary>
      <value>
      a value tag is used to describe the property value.
      </value>
    </member>
    <member name="m:testclass.somemethod(system.string)">
      <summary>
      description for somemethod.
      </summary>
      <param name="s"> parameter description for s goes here.</param>
      <seealso cref="t:system.string">
      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:testclass.someothermethod">
      <summary>
      some other method.
      </summary>
      <returns>
      return values are described through the returns tag.
      </returns>
      <seealso cref="m:testclass.somemethod(system.string)">
      notice the use of the cref attribute to reference a specific method.
      </seealso>
    </member>
    <member name="m:testclass.main(system.string[])">
      <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:testinterface.interfacemethod(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>

编译代码

若要编译该示例，请输入以下命令：

csc xmlsample.cs /doc:xmlsample.xml

此命令创建 xml 文件 xmlsample.xml，可在浏览器中或使用 type 命令查看该文件。

可靠编程

xml 文档以 /// 开头。 创建新项目时，向导会放置一些以 /// 开头的行。 处理这些注释时存在一些限制：

1.文档必须是格式正确的 xml。 如果 xml 格式不正确，则会生成警告，并且文档文件将包含一条注释，指出遇到错误。

2.开发人员可以随意创建自己的标记集。 有一组推荐的标记。 部分建议标记具有特殊含义：

• <param> 标记用于描述参数。 如果已使用，编译器会验证该参数是否存在，以及文档是否描述了所有参数。 如果验证失败，编译器会发出警告。
• cref 属性可以附加到任何标记，以引用代码元素。 编译器验证此代码元素是否存在。 如果验证失败，编译器会发出警告。 编译器在查找 cref 属性中描述的类型时会考虑所有 using 语句。
• <summary> 标记由 visual studio 中的 intellisense 用于显示有关某个类型或成员的附加信息。
  

备注

xml 文件不提供有关该类型和成员的完整信息（例如，它不包含任何类型信息）。 若要获取有关类型或成员的完整信息，请将文档文件与对实际类型或成员的反射一起使用。

以上就是c#如何使用 xml 文档功能的详细内容，更多关于c# 使用 xml 文档功能的资料请关注其它相关文章！