Adding VBdocman Comment

General

VBdocman works fine without any additional comment. All Applies to, Methods, Properties and Events 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, Examples links 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 VBdocman understands. This is classical VB comment with some additional features. (It is very similar to JavaDoc comment):

The first line must be '**

VBdocman comment block ends with first non comment line.

VBdocman comment block must be located immediately before commented object (method, function, property, event, ...), only empty lines are allowed between them. If there is some other line between them (usual VB comment), then VBdocman comment block is ignored. One exception is when commenting whole module. Then comment block must start on the first line of module.

Example:

'**
'This is good VBdocman
'comment.


Public Sub clear() 
End Sub 


'**
'This is not good VBdocman comment because it 
'is not immediately before declaration.


'dummy comment
Public Sub clear() 
End Sub 

VBdocman comment blocks placed in the body of an object are ignored. Only one VBdocman comment block per object declaration statement is recognized. Note, if there are more variables or constants in one line, all of them appear in documentation, but their descriptions may be invalid.

A comment is a description followed by tags. The description begins after the starting delimiter '** and continues until the tag section. The tag section starts with the first character @ that begins a line (ignoring leading quote). The description cannot continue after the tag section begins. There can be any number of tags -- some types of tags can be repeated while others cannot. This @see starts the tag section:

'**
'Clears the playing field. 
'
'@see .field 
'@see .setCell 
'@rem All cells are set to 0. 
Public Sub clear() 
End Sub 

Leading quotes. When VBdocman parses a VBdocman comment, leading quote (') characters on each line are discarded; blanks and tabs preceding the initial quote (') characters are also discarded. Everything after that quote including leading white space is being left, such as when indenting sample code.

When commenting properties it is not necessary to add comment to all get/set, get/let or get/set/let methods. It is sufficient to comment just one of them. If more of them are commented then the order to choose the comment is get, set and then let with the lowest priority.

Automatic Addition of Comment

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

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

  1. Add VBdocman Comment automatically adds the default comment to the object over which there is a cursor. If that object is a method, function, property or event, user can preset which tags will be added automatically (see Comment Options). It is good for quick inserting of basic comment.

    Example of automatically added default comment

  2. Comment Editor invokes the Comment editor for selected object. This is useful when creating complicated documentation including cross-references, parameters settings and others. Comment editor provides the user-friendly graphical way for editing the comments. If the Comment editor is invoked on object without VBdocman comment, it is automatically filled by default VBdocman comment for that object.

    Example of VBdocman Comment Editor

 

There is one more item in the pop-up menu, Copy Selection as Code. You can select any part of your source code and click this item. The code is formatted for use in VBdocman comments and copied into clipboard. The $CODE$ macro is added to the beginning and $END-CODE$ macro to the end of code. The $EOL$ macro is appended to the end of each line. You can then paste it anywhere in your VBdocman comments.

This way you can include examples directly in the comments.


Send feedback to Helixoft
© 2000-2005 Helixoft. All rights reserved.