Child pages
  • JSDoc Annotations
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 25 Next »

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 Script Editor in Servoy Developer supports annotating the JavaScript code with JSDoc. 

Annotating JavaScript using JSDoc allows the build process to generate more precise builder markers that, based on the configuration produce either markers of the level ERROR, WARNING or INFO.

As JavaScript is a weaktyped, dynamic language, by default it is not possible to automatically analyse the code to check it's correctness

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:

/**
 * A simple demo function that outputs some text
 * @author pbakker
 * @private
 *
 * @param {String} text The text that will be written to the output
 * @throws (String)
 * returns Boolean
 *
 * @example try {
 *    saySomething('Hello world!');
 * } catch(e) {
 *
 * }
 *
 * @see application.output
 * @since 1.0
 * @version 1.0.1<br>
 * - Added some more JSDoc tags for the demo
 */
function saySomething(text) {
  if (text == null || text.length == 0) {
    throw "Invalid input!"
  }
  application.output(text);
  return true;
}

Auto generated tempaltes

Control-Shift-J

Code Completion

JSDoc Tags

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

 

Indicates the author of the code

@constructor

@constructor

function

 

...

@deprecated

@deprecated

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.

@example

@example

function

 

Tag allowing to provide some sample code how to use the function or variable. Multiline content is possible my including "<br>" as line-breaks behind each line of content

@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 no

Describe function parameters.
The tag must be followed by a #Type Expression and a name
The "name" must match the name of one of the parameters in the function declaration.

@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

@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

@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

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

 

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 (warnings)

function

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

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

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

@version

@version versionDescription

function, variable

 

Tag to provide information about the version of the code

(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

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

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

 

AnyType

*
Any type of value

@param, @return, @type, @throws

 

OR Type

{String|Number}
Either a String or a Number

@param, @return, @type, @throws

 

REST Type

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

@param

 

Array Type

{String[]}


{Array<String>} 
An array containing just string 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

 

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

 

^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

  • No labels