• General
• Automatic Addition of Comment

General

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 in VB6 code.

Both methods are based on tags that are included in your comments. The tags are almost the same in both types, they only differ in syntax. 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

  '''<summary>Methos summary goes here.</summary>
  '''<remarks>This is remarks section.</remarks>
  Sub myMethod()

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.

Automatic Addition of Comment

User can write all that comment manually but he is not required to do so. VSdocman can do that automatically.

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 which tags will be added automatically (see Comment Options). It is good for quick inserting of basic comment. The type of comment is XML only, @-style comments are not supported.

   

   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 VSdocman comment, it is automatically filled by default VSdocman comment for that object. Editor produces only XML comments, but it can recognize also @-style comments which will be automatically converted to XML format.

   

   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 or @-style comments, short property description in Properties Window must be defined with System.ComponentModel.Description attribute. See information about context-help.
   

   

   Automatically added Description attribute

 

See Also

XML comments | Comment tags | Comment editor | Comment Options