When writing Servoy Developer IDE
The Script Editor in the Servoy Developer IDE supports annotating JavaScript code using JSDoc. Documenting the code is a good practise, as it makes it easier to understand the code after a while or if another programmer needs to have a look at it.
Within Servoy, there is
The JSDoc syntax supported by the Servoy Developer IDE is derived from the JSDoc Toolkit and Google Closure Compiler's support for JavaScript annotation, plus some custom Servoy extensions.
The JSDoc syntax consists of a set of JSDoc tags. Some of these tags require a Type Expression as one of the parameters.
JSDoc:
/**
*
*
*/
Auto generated tempaltes
Control-Shift-J
Code Completion
JSDoc Tags
Tag |
Syntax & Examples |
Context |
Comments |
---|---|---|---|
@AllowToRunInFind |
@AllowToRunInFind |
function |
Custom Servoy JSDoc tag to annotate a function that it can be run if the Form on which the function is ran is in FindMode |
@author |
@author {userName} |
function, variable |
Tag indicating the author of the code |
@constructor |
@constructor |
function |
... |
@deprecated |
@deprecated |
function, variable |
Tag indicating that the function or variable is obsolete or has been replaced and should be used anymore |
@example |
@example |
function |
Tag allowing to provide some sample code how to use the function or variable |
@param |
@param {Type} name parameterDescription |
function |
Tag to describe function parameters |
@private |
@private |
function, variable |
Annotates a variable or function as accessible only from within the scope1 in which it is declared |
@protected |
@protected |
function, variable |
Annotates a variable or function as accessible from within the scope1 in which it is declared and all scopes that extend this scope |
@return |
@return {Type} |
function |
Annotates the type of the returned value |
@returns |
@returns {Type} |
function |
alias for @return |
@see |
@see seeDescription |
function, variable |
Tag to provide pointers to other parts of the code that are related |
@since |
@since versionDescription |
function, variable |
Tag to provide information about in which version of the code the variable or function was introduced |
@SuppressWarnings |
@SuppressWarnings (warning) |
function |
Custom Servoy JSDoc tag to suppress builder markers of a certain type within a function |
@throws |
@throws {Type} |
function |
Tag to describe the type of Exceptions that can be raised when the function is called |
@type |
@type {Type} |
variable, inline variable |
Tag to specify the type of the value that a variable can hold |
@version |
@version versionDescription |
function, variable |
Tag to provide information about the version of the code |
1 A scope can be either a Form or the globals scope. Only Form can be extended, thus the @protected tag is not relevant for annotating variables and functions within the globals scope
Type Expressions
Type Expressions are used to describe the type and/or structure of data in the following cases:
Use case |
Tag |
Example |
---|---|---|
function parameters |
@param |
/** |
function return type |
@return |
/** |
functions exceptions |
@throws |
/** |
variables |
@type |
/** |
|
|
|
A Type Expression is to always be surrounded by curly braces: {typeExpression}. Note that when using the Object Type expression variation that start and stops with curly braces as well, this results in double opening and closing braces.
Expression name |
Syntax example |
Context |
Comments |
---|---|---|---|
Named type |
{String} |
@param, @return, @type, @throws |
|
AnyType |
* |
@param, @return, @type, @throws |
|
OR Type |
{String|Number} |
@param, @return, @type, @throws |
|
REST Type |
{...String} |
@param |
|
Array Type |
{String[]} |
@param, @return, @type, @throws |
|
Object Type |
{Object<String>} |
@param, @return, @type, @throws |
|
Object Type with optional properties |
{ {name:String, [age]:Number}} |
@param, @return, @type, @throws |
|
JSFoundSet type |
{JSFoundset<db:/udm/contacts>}1 |
@param, @return, @type |
|
JSRecord type |
{JSRecord<db:/udm/contacts>}{^}1^ |
@param, @return, @type |
|
JSDataSet type |
{JSDataSet<{name:String, age:Number}>} |
@param, @return, @type |
|
RuntimeForm Type |
{RuntimeForm<superFormName>} |
@param, @return, @type |
|
^1^ the value in between <..> is the datasource notation that is built up of the database server and tablename: db:/{serverName}/{tableName}
Adding whatever tag you like
Code completion
JSDoc Templates
Tip: Check out the JSDoc plugin for Servoy Developer on ServoyForge
Old 5.x style of annotating:
JSRecord:servername.tablename
JSFoundset :servername.tablename
Form:formname