Documenting Your Code with XML - Visual Basic (original) (raw)

In Visual Basic, you can document your code using XML.

XML documentation comments

Visual Basic provides an easy way to automatically create XML documentation for projects. You can automatically generate an XML skeleton for your types and members, and then provide summaries, descriptive documentation for each parameter, and other remarks. With the appropriate setup, the XML documentation is automatically emitted into an XML file with the same root file name as your project. For information about configuring the generation of the XML documentation file, see -doc compiler option and GenerateDocumentationFile MSBuild property.

The XML file can be consumed or otherwise manipulated as XML. This file is located in the same directory as the output .exe or .dll file of your project.

XML documentation starts with '''. The processing of these comments has some restrictions:

• The documentation must be well-formed 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. There is a recommended set of tags (see XML Comment Tags). Some of the recommended tags have special meanings:
  • The 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.
  • 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. The compiler also respects any Imports statements when looking for a type described in the cref attribute.
  • The
    tag is used by IntelliSense in Visual Studio to display additional information about a type or member.

Related sections

For details on creating an XML file with documentation comments, see the following topics:

• -doc
• XML Comment Tags
• Processing the XML File
• How to: Create XML Documentation
• XML Tools in Visual Studio

See also

• Developing Applications with Visual Basic
• Visual Basic Programming Guide