Visual Basic .NET XML Documentation Tool

The XML Documentation Tool (XML Documentation Tool.exe) gives Visual Basic .NET developers the ability to author XML documentation files for their library projects.  This is useful when it is desirable to distribute a built assembly but impractical to distribute associated source code.  Consumers of their referenced libraries see the XML information in Intellisense in the Visual Studio code editor and the Object Browser.

Note The tool can be used for assemblies built in languages other than Visual Basic .NET, as long as the assemblies are CLS compliant managed code assemblies, such as C#.

To start the tool 

  1. Start the XML Documentation Tool by double-clicking XML Documentation Tool.exe from its downloaded location. The XML Documentation Tool window appears. 
  2. To access the assembly you want to examine, on the File menu, click Open. The Open Files dialog box appears. 
  3. Enter the name of the assembly or select Browse to search for the file. If an XML file is already associated with the assembly, it appears in the XML File text box. 
  4. Click OK to open the assembly. A tree view of the assembly members is displayed in the left pane.

Note The four most recently used assemblies are listed under the File menu.

To expand or collapse the tree view

To edit XML documentation

To search for a specific member

  1. On the Edit menu, click Find. The XML Documentation Find dialog box opens.
  2. In the Find text box, type the name of the item and click Find Next.
  3. Select the Match Case or Match Whole Word check boxes to refine your search.

Accessing Your XML file

When you add a reference to a component in another project, Visual Studio automatically reads the XML file that has the same file name (with an .xml extension) and that is in the same directory as the .dll file. When you call methods from that assembly in the code editor, the XML documentation about each argument is displayed in Intellisense. You can view summary, parameters, and remarks in the Object Browser.

To view your information

  1. Open your project.
  2. On the View menu, click Other Windows, and then Object Browser. The Object Browser window appears.
  3. Locate the library in the Objects pane.
  4. Click on a member to view the information associated with it. The information appears in the Description pane.

Error Information

When there are conflicts between the information in the XML file and the assembly, the XML Documentation tool lists these conflicts as errors, along with the path to the node creating the error and a brief description of the error. The status bar displays the number of errors. Errors occur when the assembly and its XML documentation file are out of sync. For example, a developer may have changed the name of a class in one file but not the other, or a developer may have added a parameter for a method.  Error information appears in the Error Window, which is located in the lower-right pane, and can be hidden or displayed. To hide and display error information, click Show Error Window on the View menu.  Double-click an item in the error list to highlight the node in the left pane and display the contents of the node. Nodes with associated errors are displayed in red.

To correct errors

The following table lists errors that might appear in the Error Window.

Error

Possible Cause

This node found only in the XML file.

The node appears in the XML file, but not in the assembly. Delete the node to remove this error.

Duplicate <fieldname> field found.

A node contains duplicate fields.In the editor window, right-click on the field and select Delete from the context menu.

Unexpected <fieldname> found. Only <type> can have <fieldname> fields.

A node contains an inappropriate field.In the editor window, right-click on the field and select Delete from the context menu.

'Name' item for parameter on node <nodename> is not valid.

The name item for an XML node is not valid. Delete the node.

Parameter <parametername> on node <nodename> is found only in the XML file.

The parameter appears on the node only in the XML file. Edit the node information to remove this error.

Field <fieldname> is unrecognized; content is ignored. Content: <message>.

Copy the content of the field to another node if you wish to preserve it and delete the node.

Node name <nodename> is not valid. This node will be removed upon save.

A nodename is not valid. Save the application to remove the node and its corresponding error.

'Name' item for member node is not valid. This node will be removed upon save.

A member name is not valid. Save the application to remove the node and its corresponding error.

Bad signature found in member node: <nodename>.

The signature for an XML node is not valid. Delete the node.

For more information, see the following topics in the Visual Studio .NET help system:

Processing the XML File

Viewing Code Structure with Comments

Creating Code Reports

Browsing Code and Components

Last Update: 9 July 2002