VSdocman works fine without any additional comment. All Methods, Properties, Events and other links are generated properly and parameters description tables and other fields are also included. But a user is then forced to add some additional information into these fields (describe parameters, add See Also, Exceptions links, examples and others) later. And it must be done every time when the new documentation is generated.

To avoid that you can include that information directly into your source code. It is done by adding special comments which VSdocman (and Visual Studio) understands. VSdocman understands two types of comments:

1.Standard XML comments which can be used in both C# and VB .NET. This is the recommended comment type and VSdocman comment editor can generate only this one.

2.@-style comments which are very similar to JavaDoc comment. These comments are only recognized in VB .NET code and VSdocman can read them only for historical reasons because they were used by old VBdocman for VB6 code.

Commenting is based on the tags that are included in your comments. XML tags have standard XML syntax. XML comments have prefix which can be defined by user, default is  /// for C# and ''' for VB.

For example

XML comments are described here in detail. If you wish to add comments manually, the best way to learn them is to use the Comment editor first.

User can write XML comment manually but he is not required to do so. VSdocman can do that automatically. VSdocman has an intelligent mechanism for inserting comments. Depending on code element name or type, you can easily insert predefined default comment. For example, the "Gets or sets a value indicating whether ..." summary text is automatically generated for boolean properties. This is controlled by comment templates which are fully customizable by user. There are some predefined templates for the most common cases.

When user clicks right mouse button on the code window, the pop-up menu appears. Menu contains Add XML Comment, Comment Editor and Add Description Attribute items which perform the following actions:

1.Add XML Comment automatically adds the default XML comment to the current member. User can preset how the default comment should look like (see Comment Templates). It is good for quick inserting of basic comment.

Example of automatically added default comment

2.Comment Editor invokes the Comment editor for selected member. This is useful when creating complicated documentation including hyperlinks, text formatting and others. Comment editor provides a user-friendly WYSIWYG way for editing the comments. If the Comment editor is invoked on member without an XML comment, it is automatically filled by a default XML comment for that object.

Example of VSdocman Comment Editor

3.Add Description Attribute automatically adds the Description attribute to the current member. While documentation, F1 help and IntelliSense information is extracted from XML comments, the short property description in Properties Window must be defined with System.ComponentModel.Description attribute. See information about context-help.

Automatically added Description attribute

XML comments | Comment tags | Comment editor | Comment Options