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
Note The four most recently used assemblies are listed under the File menu.
To expand or collapse the tree view
or
To edit XML documentation
Note The windows holding information about the individual members appear in the upper-right pane.
To search for a specific member
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
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
Note Before correcting any errors, you may want to copy information from one node to another by dragging the node you want to copy to the second node in the tree view. Information is copied for all nodes that match.
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