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|http://code.google.com/p/jsdoc-toolkit/] and [Google Closure Compiler's support for JavaScript annotation|http://code.google.com/closure/compiler/docs/js-for-compiler.html], 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
h3. 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 scope{^}1^ in which it is declared |
| @protected | @protected | function, variable\\ | Annotates a variable or function as accessible from within the scope{^}1^ 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
h3. 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 | /*\* \\
\* @param \{String} value Just some string value \\
*/ \\
function demo(value) \\
\{...} |
| function return type \\ | @return\\
@returns | /*\* \\
\* @param \{String} value Just some string value \\
\* @return \{\{x:Number, y:Number}} */ \\
function demo(value) \{ \\
... \\
return \{x: 10, y: 20} \\
} |
| variables \\ | @type | /*\* \\
\* @type \{XML} \\
*/ \\
var html = <html> \\
<head> \\
</head> \\
<body> \\
Hello World\! \\
</body> \\
</html> |
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 || Comments ||
| Named type | \{String} \\
\{Boolean} \\
\{Number} \\
\{XML} \\
\{XMLList} \\
\{RuntimeForm} \\
\{RuntimeLabel} \\
\{JSButton} \\
\{JSForm} | |
| AnyType | \* | |
| OR Type | \{String\|Number} | |
| REST Type | \{...String} | |
| Array Type | \{String\[\]} \\
\{Array<String>} \\
\{Array<Byte>} | |
| Object Type | \{Object<String>} \\
\{Object<Array<String>>} \\
\{name:String, age:Number}} \\ | |
| Object Type with optional properties | \{ \{sDocID:String, \[sTemplateID\]:String}} \\
\{ \{sDocID:String, sTemplateID:String=}} | |
| JSFoundSet type | \{JSFoundset<db:/udm/contacts>}{^}1^ \\
\{JSFoundset<\{column1:String, column2:Number}>} | |
| JSRecord type | \{JSRecord<db:/udm/contacts>}{^}1\^ \\
\{JSRecord<\{column1:String, column2:Number}>} | |
| JSDataSet type | \{JSDataSet<\{name:String, age:Number}>} | |
| RuntimeForm Type | \{RuntimeForm<superFormName>} | |
\^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|https://www.servoyforge.net/projects/jsdoc] on [ServoyForge|https://www.servoyforge.net/]
Old 5.x style of annotating:
JSRecord:servername.tablename
JSFoundset :servername.tablename
Form:formname |