为自己的类添加说明文字

王朝other·作者佚名  2006-01-09
窄屏简体版  字體: |||超大  

http://msdn.microsoft.com/library/chs/default.asp?url=/library/CHS/csref/html/vcwlkXMLDocumentationTutorial.asp

教程C# 提供一种机制,供开发人员使用 XML 将其代码存档。在源代码文件中,以下代码行可以作为注释处理并放在文件中:以 /// 开始的行;在用户定义的类型(如类、委托或接口)、某成员(如字段、事件、属性或方法)或某命名空间声明之前的行。

示例下面的示例提供对某个已存档的类型的基本概述。若要编译该示例,请键入以下命令行:

csc XMLsample.cs /doc:XMLsample.xml

这将创建 XML 文件 XMLsample.xml,您可以在浏览器中或使用 TYPE 命令查看该文件。

// XMLsample.cs

// compile with: /doc:XMLsample.xml

using System;

/// <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 SomeClass

{

/// <summary>

/// Store for the name property</summary>

private string myName = null;

/// <summary>

/// The class constructor. </summary>

public SomeClass()

{

// 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 ( myName == null )

{

throw new Exception("Name is null");

}

return myName;

}

}

/// <summary>

/// Description for SomeMethod.</summary>

/// <param name="s"> Parameter description for s goes here</param>

/// <seealso cref="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 results 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;

}

/// <summary>

/// The entry point for the application.

/// </summary>

/// <param name="args"> A list of command line arguments</param>

public static int Main(String[] args)

{

// TODO: Add code to start application here

return 0;

}

}

代码讨论XML 文档以 /// 开头。创建新项目时,向导将为您放入一些起始 /// 行。对这些注释的处理有一些限制:

文档必须是符合标准格式的 XML。如果 XML 不符合标准格式,将生成警告,并且文档文件将包含一条注释,指出遇到错误。有关符合标准格式的 XML 的更多信息,请参见 XML 词汇表。 开发人员可自由创建自己的标记集。有一套建议的标记(请参见“其他阅读材料”部分)。某些建议的标记具有特殊含义: <param> 标记用于描述参数。如果使用,编译器将验证参数是否存在,以及文档中是否描述了所有参数。如果验证失败,则编译器发出警告。 cref 属性可以附加到任意标记,以提供对代码元素的引用。编译器将验证该代码元素是否存在。如果验证失败,则编译器发出警告。查找 cref 属性中描述的类型时,编译器还考虑任何 using 语句。 <summary> 标记由 Visual Studio 内的“智能感知”使用,用来显示类型或成员的其他相关信息。

在 Visual Studio 开发环境中设置此编译器选项 若要将生成的 .xml 文件用于智能感知功能,请使该 .xml 文件的文件名与要支持的程序集同名,然后确保该 .xml 文件放入与该程序集相同的目录中。这样,在 Visual Studio 项目中引用程序集时,也可找到该 .xml 文件。

单击“配置属性”文件夹。

单击“生成”属性页。 修改“XML 文档文件”属性。 <summary></summary> 描述类型成员。 <remarks></remarks> 指定类或其他类型的概述信息。 <param></param> 在方法声明的注释中使用以描述该方法的一个参数。 <returns></returns> 在方法声明的注释中使用以描述返回值。 <newpara></newpara> 在注释中开始一个新段落。

 
 
 
免责声明:本文为网络用户发布,其观点仅代表作者个人观点,与本站无关,本站仅提供信息存储服务。文中陈述内容未经本站证实,其真实性、完整性、及时性本站不作任何保证或承诺,请读者仅作参考,并请自行核实相关内容。
 
 
© 2005- 王朝網路 版權所有 導航