Stage 3 - Select comment types to include

This stage allows you to control which comments will be extracted from your source code and included in the generated HTML Help file.

Comments can be extracted by Document! VB in two ways, Automatic and Tagged.  Automatic association associates any comment lines immeadiately preceeding a code element with the element for inclusion in the generated documentation.  Document! VB can automatically associate and extract comments associated with Blocks (Functions, Subs and Properties), Variables, Events, Enumerations and Declare statements.  Any comments appearing before any other line in a component are associated with the component itself.

Tagged association allows you to explicitly identify source code comments as associated with a particular code element.  In order to have comments included for Parameters and Return Types, you need to tag them in your source code, Document! VB can not associate them automatically.  You may want to read up on how to explicitly tag source code comments or look at the examples below.

By default, Document! VB will extract all comment types, both automatic and tagged.  If both comment types are found for a single code element, or if multiple comment lines exist, comments will be concatenated together in the order they appear in the code, with a space inserted between each line found.

It is possible to insert hyperlinks to other parts of your code, and / or to insert HTML tags in your comments for more precise formatting - refer to advanced comment extraction tips for details.

Examples

The following sample code illustrates the use of each of the automatic and tagged comment types.

' An XML document element. An element can have
' properties and text associated with it.

' ##CD An XML document element. ...
<- automatically be extracted as a component description

<- explicitly identified as the component description


' The name of the element
Public Name As String
' The type of the element
Public TypeName As xmlElementTypeEnum

' ##VD TypeName The type of the element


' Valid types of Element
Public Enum xmlElementTypeEnum
   xmlStringType = 1  ' A string element
   xmlNumericType = 2
End Enum

' Fired when the element has been loaded
Event Loaded()

' Copy memory to populate API structure
Public Declare Sub CopyMemory Lib "kernel32" Alias _
"RtlMoveMemory" (Destination As Any, Source As Any,_
ByVal Length As Long)


<- associated with the property 'Name'

<- associated with the property 'TypeName'

<- explictly identified as the variable description for the 'TypeName' variable

<- associated with the enumeration 'xmlElementTypeEnum'
<- associated with the enumeration member


<- associated with the event 'Loaded'


<- associated with the Declare statement 'CopyMemory'


' Load the element from the passed string
Public Function Load(Source As String) As Boolean

' ##BD Load the element from the passed
' ##BD  string

' ##PD Source A valid string containing an
' ##PD  XML Element

' ##RD Indicates success or failure of the
' ##RD  load operation

End Function


<- associated with the Method 'Load'


<- explicitly identified as the Block description for the method 'Load'

<- explicitly identified as the Parameter description for the parameter 'Source'

<- explicitly identified as the Return Type description for the method 'Load'


< Previous Stage     Next Stage >