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 the 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 source code. It is done by adding special comments which VSdocman understands. VSdocman understands two types of comments:

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

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

Commenting is based on 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 VB and /// for C#.

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 Comment editor first.

User can write all that comment manually but he is not required to do so. VSdocman can do that automatically. VSdocman has 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 cross-references, text formatting and others. Comment editor provides the user-friendly WYSIWYG way for editing the comments. If the Comment editor is invoked on member without XML comment, it is automatically filled by 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, 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