LotusScript.doc - Documentation syntax

Documentation syntax

This page shows the syntax you must use when documenting code using LotusScript.doc.

Table of contents

Comment syntax
Comments are written using a syntax much like the one used in javadoc where the /** character sequence starts a comment and the */ character sequence ends a comment. The comment should immediately preceed the type (function, sub, class etc.) to be documented. As you can see below you need to prefix the lines with a ping (') to make the lines into LotusScript comments.

'/**
' * This is the comment text. A comment may span multiple 
' * lines. 
' * <p></p>
' * You can use HTML in your comments.
' */
Public Sub Initialize()

End Sub

As you can see above you can use standard HTML tags in your comments to highlight text or to use bulleted lists.

When writing comments please note that in the summary tables only the first sentence is shown. The first sentence is all characters from the start to the first encountered period or until the end of the comment is there are no periods in the comment. In the above example the first sentence is "This is the comment text.".

Special case
When writing subs and functions in global scope, that is outside classes in script libraries or directly in design elements, you can put the comment inside the sub or function. This makes it easier to copy/paste the code to another place and have the comment follow the code and not go to the Declarations-section.

Sub Queryopen(Source As NotesUIDocument)
'/**
' * This is the comment for my Queryopen event inside the sub-body to 
' * make copy/pasting easier.
' */
End Sub

Annotations / @-parameters
Annotations are a special type of comment that has special meaning in LotusScript.doc. You use annotations to document special types of information about a type such as method parameters, return types etc.

Annotations are written as part of the comment it self near the end as the below example shows.

'/**
' * Adds a recipient to the e-mail. 
' * <p></p>
' * @param recipient_type Use the XXX_RECIPIENT constants to signal the type of recipient (To, CC, BCC).
' * @param username The address to send to
' * @error 9999 If the supplied type isn't one of the allowed XXX_RECIPIENT constants
' */
Public Sub AddRecipient(recipient_type As Integer, username As String)
   Select Case recipient_type
   Case Is = TO_RECIPIENT
      Call Me.pAddRecipient(username, Me.pToRecipients)
   Case Is = CC_RECIPIENT
      Call Me.pAddRecipient(username, Me.pCcRecipients)
   Case Is = BCC_RECIPIENT
      Call Me.pAddRecipient(username, Me.pBccRecipients)
   Case Else
      'invalid type
      Error 9999, "Invalid type supplied"
   End Select
End Sub

The resulting documentation from the above Sub will look like the below screenshot.

As you can see the parameters (@param annotations) and the possible error code(s) (@error annotation) has been highlighted in separate sections which makes them easy to find.

Please note: Annotations cannot span lines - if the annotation is broken into lines the text will be trucated.

See the @-parameters section for information on the supported annotations.

Design element description
A design element description is a description that applies to the design element in a LotusScript.doc sense. I opted to have a separate description instead of using the normal design element comment since the design element description is more geared towards explaining that the code does - not as much what the design element does. It is of cause true that the distinction is smaller when discussing script elements.

For the reader familiar with javadoc this is much like the package.html file in javadoc.

A design element description can be added to all supported design elements but note that it should be added in the "Globals"-section for views and forms.

The design element description is the comment shown in the summary tables as shown below.

A design element description is added by writing a Sub (method) with a special name and signature. The actual description should be enclosed in a %REM statement like shown below.

Private Sub lsdoc_description
%REM

%END REM
End Sub

As mentioned in the section on comment syntax you may use HTML to format your design element descriptions. As you can see from the above example the summary table only shows the first sentence whereas the documentation for the design element shows the entire comment.

Supported design elements
The following design elements are supported:

Form
View
Agent
LotusScript script Library
Page
Shared Actions
Database script

Supported code constructs
The following code constructs are supported:

Classes
Class inheritance
Subs (also inside custom classes)
Functions (also inside custom classes)
Types
Properties (inside classes)
Constants

Supported @-parameters
LotusScript.doc supports the following @-parameters:

@param
@return
@depends
@see
@error
@version
@author

The table below shows the syntax and example usage of each of the parameters.

Parameter	Syntax	Description
@param	@param <param_name> <description> Example: @param doc The NotesDocument to be processed. If Nothing is supplied a new document is created in the current database.	Documents a parameter to a sub or a function allowing you to specify what data is valid for the parameter. Valid for subs and functions.
@return	@return <description> Example: @return A NotesDocument representing the underlying document.	Documents the return type for a function. Valid for functions.
@depends	@depends <design element name> Example: @depends “Memo”-form.	Documents which design element(s) the code depends on. Valid for subs, functions, properties and classes.
@see	@see <type name>#<sub/function name> Example: @see Email#Send	Specifies a reference to another place in the documentation resulting in a HTML-link to the location. Valid for subs, functions, properties and classes.
@error	@error <error code> <description> Example: @error 7890 Raised if the supplied database is Nothing or hasn’t been opened.	Documents an error that may be raised by the code. Valid for subs, functions, properties and classes.
@version	@version <description> Example: @version 1.2	Specifies the version of the class / sub / function. Valid for subs, functions, properties and classes.
@author	@author <author> Example: @author Mikkel Heisterberg	Specifies the author of the class / sub / function. Valid for subs, functions, properties and classes.

Change history
This section describes the changes to this document after its initial release.

Date of change	Description
1 August 2005	First version and initial release of syntax documentation.
9 August 2005	Fixed typo in @-parameter section (@returns --> @return). Thanks Chad.
21 August 2005	Added @version @-parameter
25 October 2005	Added @author @-parameter and update support design elements.