c#如何使用 XML 文档功能
程序员文章站
2022-11-06 09:50:26
下面的示例提供对某个已存档类型的基本概述。示例// if compiling from the command line, compile with: -doc:yourfilename.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 文档功能的资料请关注其它相关文章!