Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

On mouse hover or autocomplete, the documentation of the super function is displayed. This can go through multiple levels, as long as this tag is present.

Tag

Syntax & Examples

Context

Impact

Description

@AllowToRunInFind

@AllowToRunInFind

function

Determines if the function will be executes in FindMode when used as an event handler

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

none

Indicates the author of the code

@constructor

@constructor

function

This will show a different icon on the Script Outline view and suppresses warnings related to inconsistent return values when building in a fail-save to calling a constructor function without the new keyword

 


@deprecated

@deprecated description

function, variable

Accessing a deprecated variable or calling a deprecated function will produce a builder marker in Servoy Developer

Indicates that the function or variable is obsolete or has been replaced and should be used anymore.
Use an (optional) description to provide reasoning and possible alternatives

@enum

@enum


Example:
/**
 * @enum
 */
var TEAM_COLORS = {
    RED : 1,
    GREEN : 2,
    BLUE : 3
}

variablenone in scripting, but Servoy Relations

Variables that contain a JavaScript Object with key/value pairs and are tagged as enumeration using the @enum tag have special meaning in Servoy relations: The relation editor allows selecting one of the keys of the object for the primary 'key' in a relation item.

Only String and Number values are supported. They are treated as constants, meaning that changes to the values made through scripting are not supported: if the value is altered, already loaded relations will not be updated accordingly.

@example

@example

function, variable 

none

Tag allowing to provide some sample code how to use the function or variable. Multiline content is possible by including "<br>" as line-breaks behind each line of content.
To have more control over the formatting of the sample code, the entire sample code can be wrapped in pre-tags: <pre>samplecode</pre>
Multiple @example tags can be defined for each function or variable

@inheritDoc@inheritDocfunctionInherit JS documentation from the super form's functionOn mouse hover or autocomplete, the documentation of the super function is displayed. This can go through multiple levels, as long as this tag is present.

@override

@override

functions

none

Tag to describe that the function is overriding an equally named function on a super form

@param

@param {Type} name parameterDescription

function

Builder markers will be generated in Servoy Developer if the function is called with values for the parameters that do not match the specified types

Describe function parameters.
The tag can be followed by a Type Expression between {} and must have a name.  
The "name" must match the name of one of the parameters in the function declaration.
When the parameter is an unknown Java object (so not a JavaScript object) or there should be any type information assigned to the parameter, the type expressing can be omitted.

@parse@parsefunctionsDepending on how many functions have this tag, it might result in an increase of the workspace build time.The @parse tag can be used to force parsing of those functions that normally are not parsed when the "Shallow parsing" preference is set.
@public@publicfunction, variableExplicitly marks a member as public API.

A member that is not marked as either public, private or protected is implicitly considered as public.

Cannot be used in combination with @private or @protected

@private

@private

function, variable

Accessing a private variable/function from outside the scope in which it is declared will generate a builder marker in Servoy Developer

Annotates a variable or function as accessible only from within the file in which it is declared

Cannot be used in combination with @public or @protected

@protected

@protected

function, variable

Accessing a protected variable/function from outside the scope in which it is declared or a child scope will generate a builder marker in Servoy Developer

Annotates a variable or function as accessible from within the same file in which it is declared and all files that extend this file

Cannot be used in combination with @public or @private

@return

@return {Type}

function

The specified type is used by the build process to determine the correctness of the code that uses the returned value and offer Code Completion

Annotates the type of the returned value.
If the function does not return any value, omit the @return tag.
The tag must be followed by a Type Expression

@returns

@returns {Type}

function

see @return

alias for @return

@see

@see seeDescription

function, variable

none

Tag to provide pointers to other parts of the code that are related

@since

@since versionDescription

function, variable

none

Tag to provide information about in which version of the code the variable or function was introduced

@SuppressWarnings

@SuppressWarnings ([deprecated], [hides], [wrongparameters], [undeclared], [unused], [nls])

function

Stop the generation of builder markers in Servoy Developer for the specified warnings

  • deprecated - markers related to referencing deprecated API
  • hides - markers related to declaring members that hide similar named members elsewhere in the scope
  • wrongparameters - markers related to calling functions with different type of parameters than specified by the function
  • undeclared - markers related to referencing members for which the build system cannot find a declaration
  • unused - marker related to a member that is not being used
  • nls - markers related to hardcoded text when builder markers for non externalized strings are enabled (disabled by default, see window > Preferences > JavaScripts > Errors/Warnings > Externalized Strings)

Custom Servoy JSDoc tag to suppress builder markers of a certain type within a function

@this

@this {Type}

function

The specified type is used by the build process for the "this" object available inside functions to determine the correctness of the code that uses the object and offer Code Completion

Tag to specify the type of the "this" object inside functions.  
The tag must be followed by a Type Expression

@throws

@throws {Type}

function

none

Tag to describe the type of Exceptions that can be raised when the function is called.
Multiple @throws tags are allowed. 
The tag must be followed by a Type Expression

@type

@type {Type}

variable, inline variable, (function*) 

The specified type is used by the build process to determine the correctness of the code that uses the variable and offer Code Completion

Tag to specify the type of the value that a variable can hold. 
The tag must be followed by a Type Expression
On functions the @type tag is an alternative for @returns, but only one of the two can be used

@typedef@typedef {Type}variablesVariables tagged using the @typedef JSDoc tag are considered definitions of types. These types can be used as type in other JSDoc tags by using the name of the variable 

@version

@version versionDescription

function, variable

none

Tag to provide information about the version of the code

@inheritDoc@inheritDocfunctionInherit JS documentation from the super form's function

(info) A file can be either a Form JavaScript file or the globals JavaScript file. Only Form can be extended, thus the @protected tag is not relevant for annotating variables and functions within the globals JavaScript file

...

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}
}

functions exceptions

@throws

/** 
 * @throws {Number} 
 */ 
function demo(value)  {
  ...
 throw -1;
}

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

Context

Comments

Named type

{String}
{Boolean}
{Number}
{XML}
{XMLList}
{RuntimeForm}
{RuntimeLabel}
{JSButton}
{JSForm}

@param, @return, @type, @throws

The complete list of available types can be seen by triggering Code Completion inside the curly braces in the Script Editor

Any type

{*}
Any type of value

@param, @return, @type, @throws

This can be used to suppress some builder markers related to apparent type inconsistencies.

OR type

{String|Number}
Either a String or a Number

@param, @return, @type, @throws 


REST type

{...String}
Indicates one or more String values

@param

Can only be used for the last declared parameter of a function

Array type

{String[]}
{Array<String>} 
An array containing just string values 

{Array<String|Number>}  
 An array containing string and/or number values 

{Array<Byte>}
An array containing just bytes

@param, @return, @type, @throws

 


Object type

{Object<String>}
An object where the value for each key is a String value

{Object<Array<String>>} 
An object where the value for each key contains arrays that in turn contains only string values

{ {name:String, age:Number}} 
An object with a "name" and "age" key, with resp. a string and number value

@param, @return, @type, @throws 


Object type with optional properties

{ {name:String, [age]:Number}}
{ {name:String, age:Number=}}
An object with a "name" and optional "age" key, with resp. a string and number value

@param, @return, @type, @throws 


Function type

{function(String, Number, Array<Object>):Boolean}
Between the bracket of the function the types of the function parameters can be sprecified. The functions returnType can be specified after the closing bracket, prefixed by a colon

@param, @return, @type 


JSFoundset type

{JSFoundset<db:/udm/contacts>}1  
A JSFoundSet from the contacts table of the udm database server

{JSFoundset<{col1:String, col2:Number}>}
A JSFoundSet with dataproviders "col1" and "col2" with resp. string and number types

@param, @return, @type

 


JSRecord type

{JSRecord<db:/udm/contacts>}1
A JSRecord from the contacts table of the udm database server

{JSRecord<{col1:String, col2:Number}>}
A JSFoundSet with dataproviders "col1" and "col2" with resp. string and number types

@param, @return, @type 


JSDataSet type

{JSDataSet<{name:String, age:Number}>}
An JSDataSet with a "name" and "age" column, with resp. a string and number value

@param, @return, @type

 


RuntimeForm type

{RuntimeForm<superFormName>}
A RuntimeForm that extends superFormName

@param, @return, @type 


RuntimeWebComponent type{RuntimeWebComponent<webComponentName>}@param, @return, @type

The webComponentName can be found in the associated spec file; webComponentName may be for example: bootstrapcomponents-tabpanel (leading to the following type: {RuntimeWebComponent<bootstrapcomponents-tabpanel>} )

CustomType{CustomType<componentName.customTypeName>}@param, @return, @typecomponentName may be web component or web service. The customTypeName is defined in the spec file. Example: {CustomType<bootstrapcomponents-tabpanel.tab>}

...