Tagging comments in your source code

You will have one of two reasons for wanting to explictly tag comments in your source code :

  1. You want finer control over how Document! VB picks out comments from your source code;
  2. You want to include comments for Parameters and / or Return Types (Document! VB cannot automatically associate comments with these items).

Tagging comments is straightforward and involves identifying the type of comment using a prefix at the start of each relevant comment line.  You can find some examples of tagged comments in the help for Stage 3 of the Document! VB Wizard and at the end of this topic.

The table below lists the prefixes for each of the comment types that can be tagged.

Prefix Comment Type Description
##CD Component This type of comment will appear in the page describing a component in overview.  A general description of component, it's purpose and usage guidelines would normally be relevant.  A component description can appear anywhere in the components source code.
##BD Block This type of comment will appear in the page describing a particular Method or property (Function, Sub or Property Let/Get/Set).  A block description can appear anywhere within the blocks code, e.g. between 'Public Sub/Function/Property ...' and 'End Sub/Function/Property'.
##VD Variable This type of comment will appear in the page describing a property (module level variable).  The comment line must be of the format '##VD [VariableName] [Comment]' where the VariableName is the name of the variable the comment is related to.  A variable description can appear anywhere AFTER the variable declaration itself.
##PD Parameter This type of comment will appear against a parameter of a Function, Sub or Property.  The comment line must be of the format '##PD [ParameterName] [Comment]' where  ParameterName is the name of the parameter the comment is related to.  A parameter description can appear anywhere within the blocks code, e.g. between 'Public Sub/Function/Property ...' and 'End Sub/Function/Property'.
##RD Return Type This type of comment will appear against a Methods (Function)Return Type.  A Return type description can appear anywhere within the blocks code, e.g. between 'Public Function ...' and 'End Function ...'.

Sample code


' ##CD This component ...  Use this component to ...

Public Name As String
' ##VD Name The textual name of this object

Public Function Load(Source As String) As Boolean

    ' ##BD This function loads an ... from a Source string

    ' ##PD Source An appropriately formatted string

    ' ##RD True = Success, False = Failure

End Function