Page History
...
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. besides that no further impact |
| ||
@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 | none | 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. | ||
@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. | ||
@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 | ||
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="c2dee86ea9a1cccf-9a062ad2-42ec40a4-aa02b8a3-a8438d88e277094ffa7e19b3"><ac:plain-text-body><![CDATA[ | @SuppressWarnings | @SuppressWarnings ([deprecated], [hides], [wrongparameters], [undeclared]) | 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. | ]]></ac:plain-text-body></ac:structured-macro> |
@throws | @throws {Type} | function | none | Tag to describe the type of Exceptions that can be raised when the function is called. | ||
@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. | ||
@version | @version versionDescription | function, variable | none | Tag to provide information about the version of the code |
...
1 the value in between <..> is the datasource notation that is built up of the database server and tablename: db:/{serverName}/{tableName}
Casting
Wiki Markup |
---|
When you have an array/object which holds some elements that you get by index (array\[1\]) or by name (array\['name'\] or object.name) and the array doesn't specify the type of the objects it holds like Array<String> or it does hold a super type so not the actual type an example is Servoy own form elements object/array. |
The elements of the form is typed as an Object<RuntimeComponent> because all elements do have that type in common. RuntimeComponent has for example the background color and so on. But if you want to have a specific property called of a certain element in the element scope/object like: elements.mylabel.text, then this text property is not someting that the RuntimeComponent type has, but that is a property of the RuntimeLabel type. So to access that text property without any warning you have to cast it.
Casting only works when making a new variable where you specify through JSDoc the type and assign the element from the Array or Object to that variable. So instead of doing this:
Code Block |
---|
elements.mylabel.text = "hallo"
|
You have to do this:
...
Type Casting
JSDoc can be used inside JavaScript code to specify the type of variables. This can be necessary if the correct type can't be automatically derived.
An example of such scenario is for example the databaseManager.getFoundSet() function. This function returns an object of the generic type JSFoundSet. In most if not all scenario's however, it is known for which specific datasource the JSFoundSet was instantiated and the foundset object will be used as such in code, accessing dataproviders on the foundset object that are specific to the datasource. This will result in builder markers, because those dataproviders are not know on the generic JSFoundSet type. Through JSDoc casting however, it's possible to specify the type of the foundset object more specifically
Code Block |
---|
/**@type {JSFoundset<db:/udm/contacts>}*/
var fs = databaseManager.getFoundSet('db:/udm/contacts') |
The difference between Code Completion with and without Type Casting can be seen in the two screenshots below. whent he Type casting is omitted, the offered Code Completion related only to the generic JSFoundset type. With the Type Casting in place, all the dataproviders of the specific datasource are also available in Code Completion:
With Type Casting:
Without Type Casting:
Another example is entries in Objects and/or Arrays: if every entry is of the same type, this can be specified on the Object/Array declaration using JSDoc, for example:
Code Block |
---|
/**@type {Array<String>}*/
var myStringArray = \[\] |
If the Object/Array contains entries of different types, the type of the entries cannot be specified when declaring the Object/Array, or only a more generic type can be specified.
An example of a generic type would be RuntimeComponent, which is the super type for RuntimeLabel, RuntimeField etc. RuntimeComponent defines all the properties and methods that all the other RuntimeXxxx types have in common. When the need arises to call methods or set properties that are specific to a specific RuntimeXxx type, the generic type can be casted:
Code Block |
---|
if (elements\[1\] instanceof RuntimeLabel) {
/**@type{RuntimeLabel}*/
var myLabel = elements\[1\]
var elementNames = myLabel.getLabelForElementName() //Calling method specific for labels
}
|
Note |
---|
Type Casting can only be performed on variable declarations. It is not possible switch the type of an already declared variable later in code |