c#如何使用 XML 文档功能

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

示例

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

/// 

/// Class level summary documentation goes here.
/// 
/// 
/// Longer comments can be associated with a type or member through
/// the remarks tag.
/// 
public class TestClass : TestInterface
{
  /// 

  /// Store for the Name property.
  /// 
  private string _name = null;

  /// 

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

  /// 

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

  /// 

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

  /// 

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

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

  /// 

  /// The entry point for the application.
  /// 
  ///  A list of command line arguments.
  static int Main(System.String[] args)
  {
    // TODO: Add code to start application here.
    return 0;
  }
}

/// 

/// Documentation that describes the interface goes here.
/// 
/// 
/// Details about the interface go here.
/// 
interface TestInterface
{
  /// 

  /// Documentation that describes the method goes here.
  /// 
  /// 
  /// Parameter n requires an integer argument.
  /// 
  /// 
  /// The method returns an integer.
  /// 
  int InterfaceMethod(int n);
}

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

  
    xmlsample
  
  
    
      

      Class level summary documentation goes here.
      
      
      Longer comments can be associated with a type or member through
      the remarks tag.
      
    
    
      

      Store for the Name property.
      
    
    
      

      The class constructor.
      
    
    
      

      Name property.
      
      
      A value tag is used to describe the property value.
      
    
    
      

      Description for SomeMethod.
      
       Parameter description for s goes here.
      
      You can use the cref attribute on any tag to reference a type or member
      and the compiler will check that the reference exists.
      
    
    
      

      Some other method.
      
      
      Return values are described through the returns tag.
      
      
      Notice the use of the cref attribute to reference a specific method.
      
    
    
      

      The entry point for the application.
      
       A list of command line arguments.
    
    
      

      Documentation that describes the interface goes here.
      
      
      Details about the interface go here.
      
    
    
      

      Documentation that describes the method goes here.
      
      
      Parameter n requires an integer argument.
      
      
      The method returns an integer.
      
    
  

编译代码

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

csc XMLsample.cs /doc:XMLsample.xml

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

可靠编程

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

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

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

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

备注

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

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