用 XML (Visual Basic)记录你的代码Document your code with XML (Visual Basic)

在 Visual Basic 中,可以使用 XML 记录代码。In Visual Basic, you can document your code using XML.

XML 文档注释XML documentation comments

Visual Basic 提供了一种简单的方法来自动创建项目的 XML 文档。Visual Basic provides an easy way to automatically create XML documentation for projects. 可以为类型和成员自动生成 XML 主干,然后提供每个参数的摘要、描述性文档和其他备注。You can automatically generate an XML skeleton for your types and members, and then provide summaries, descriptive documentation for each parameter, and other remarks. 使用适当的设置,XML 文档将自动发送到具有与项目相同的根文件名的 XML 文件中。With the appropriate setup, the XML documentation is automatically emitted into an XML file with the same root file name as your project. 有关详细信息,请参阅 -docFor more information, see -doc.

可以使用 XML 文件或以其他方式将其作为 XML 来处理。The XML file can be consumed or otherwise manipulated as XML. 此文件与项目的输出 .exe 或 .dll 文件位于同一目录中。This file is located in the same directory as the output .exe or .dll file of your project.

XML 文档以开头 '''XML documentation starts with '''. 处理这些注释时存在一些限制:The processing of these comments has some restrictions:

  • 文档必须是格式正确的 XML。The documentation must be well-formed XML. 如果 XML 格式不正确,则会生成警告,并且文档文件将会显示一条注释,指出遇到了错误。If the XML is not well formed, a warning is generated and the documentation file contains a comment saying that an error was encountered.

  • 开发人员可以随意创建自己的标记集。Developers are free to create their own set of tags. 建议使用一组标记(请参阅XML 注释标记)。There is a recommended set of tags (see XML Comment Tags). 部分建议标记具有特殊含义:Some of the recommended tags have special meanings:

    • <param>标记用于描述参数。The <param> tag is used to describe parameters. 如果使用,编译器将验证该参数是否存在,以及文档是否描述了所有参数。If used, the compiler will verify that the parameter exists and that all parameters are described in the documentation. 如果验证失败,则编译器会发出警告。If the verification fails, the compiler issues a warning.

    • cref 属性可以附加到任何标记,以提供对代码元素的引用。The cref attribute can be attached to any tag to provide a reference to a code element. 编译器验证此代码元素是否存在。The compiler verifies that this code element exists. 如果验证失败,则编译器会发出警告。If the verification fails, the compiler issues a warning. Imports查找特性中所述的类型时,编译器还会考虑所有语句 crefThe compiler also respects any Imports statements when looking for a type described in the cref attribute.

    • <summary>Visual Studio 中的 IntelliSense 使用标记显示关于类型或成员的其他信息。The <summary> tag is used by IntelliSense in Visual Studio to display additional information about a type or member.

有关创建包含文档注释的 XML 文件的详细信息,请参阅以下主题:For details on creating an XML file with documentation comments, see the following topics:

另请参阅See also