在源代码中包含帮助注释

介绍

Gambas IDE 以多种方式显示帮助页面：在帮助浏览器中、在编辑表单时在属性侧边栏中以及在设置适当的首选项时在代码编辑器中作为弹出窗口。从 Gambas 3.3 开始，您自己的代码中的帮助信息可能会出现在其中。本文档描述了如何使用“帮助注释”来实现这一点。

帮助注释 是代码注释，当以非常特定的方式构造时，它们包含在项目的 .info 文件中，然后可以由 IDE 和帮助浏览器访问以显示它们。

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.