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'