Including Help Comments in Source Code

Introduction

The Gambas IDE displays help pages in several ways: in the Help Browser, in the Properties sidebar when editing a form and in the code editor as popups when the appropriate Preferences are set. As of Gambas 3.3 it is possible to have help information from your own code appear in these. This document describes how to use "help comments" to achieve this.

Help Comments are code comments that, when structured in a very specific way, are included in the project's .info file and which can then be accessed by the IDE and Help Browser to show them.

Basically there are two types of help comments:
  • Class level, and

  • Symbol level.

Both Class and Symbol level help comments can be enhanced by using the Gambas markdown syntax.

Class Help

Class level help comments are denoted by 3 ' (apostrophes) followed by a space at the beginning of the line, e.g. 
''' This class represents a customer.

Class level help comments must be the first lines in the class header after the class "magic" line, separated from that line by one or more blank lines and separated from any following comments or code by at least one blank line. For example: 
' Gambas class file

''' This class represents the base metadata for a property exposed by the target class.
''' Properties are characterised by their Kind and specialised classes descending from
''' this class represent the nuances of each kind.
'''
''' A property is a **typed** , **named** , ( **unscoped** ) symbol.

Export
Inherits MSymbolDef

...
will work, but 
' Gambas class file

Export
Inherits MSymbolDef

''' This class represents the base metadata for a property exposed by the target class.
''' Properties are characterised by their Kind and specialised classes descending from
''' this class represent the nuances of each kind.
'''
''' A property is a **typed** , **named** , ( **unscoped** ) symbol.

...
won't.

Symbol Help

Symbol level help comments are denoted by 2 ' followed by a space. They can be placed either just before the symbol declaration (in which case they can be multi-lined) or at the end of the symbol declaration line (in which case they can only be a single line). Examples: 
'' The name property exposes the name of the customer
'' owning this account.
Property Name As String
or 
Property Name As String '' The Name property exposes the name of the customer owing this account

It is possible to put links in the symbol level help comments to other symbol help. For example: 

Dim IntroYear as Integer 	'' The year in which the vehicle becomes available
Dim IntroMonth as Integer	'' The month in the [../introyear] the vehicle becomes available

Tips and Caveats

Class level help comments will not appear unless the class is exported.

Class level help comments do not appear or are not updated until the project is compiled.

Symbol level help comments will appear in the IDE popup as soon as the class is saved.