Date: Thu, 28 Mar 2024 19:16:30 +0000 (UTC) Message-ID: <143082282.10761.1711653390970@911f0a1bad02> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_10760_1676959880.1711653390970" ------=_Part_10760_1676959880.1711653390970 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
The Script Editor in Servoy Developer offers full code completio= n (a.k.a. IntelliSense or autocomplete) and designtime code validation.
= =20As JavaScript has no means to declare the type of a variable, the type o= f a function parameter or the return type of a function, it is not possible= to get 100% correct results by just analyzing the JavaScript cod= e itself.
=20In order to improve the quality of the code completion and code validati= on, functions and variables can be annotated with JSDoc to provide the miss= ing information.
=20Besides the benefits for code completion and validation, adding JSDoc to= JavaScript code also improves the readability of the code for other develo= pers, as JSDoc allows for adding more info than just the typing info.
= =20Usin= g the JSDoc plugin hosted on ServoyForge= it is also possible to generate HTML documentation of the JavaScript = code in a Solution, based on the JSDOc supplied.
=20The JSDoc syntax consists of a set of JSDoc tags, contained in JSDoc com= ments.
=20JSDoc comments are like multi-line JavaScript comments, but the opening = tag is '/*' instead of just '/'
=20Some of the JSDoc tags require a Type Expression as one of the parameter= s and most allow for an extra description behind the tag and it's parameter= s.
=20Example
=20/** * A simple demo function that outputs some text * @author Tom * @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 =3D=3D null || text.length =3D=3D 0) { throw "Invalid input!" } application.output(text); return true; }=20
JSDoc is not a official standard, but the defacto standard is is defined= by the JSDoc Toolkit project. The other major d= efiner of JSDoc is Google Closu= re Compiler's support for JavaScript annotation.
=20The JSDoc syntax supported by the Servoy Developer IDE is derived from t= he JSDoc Toolkit and Google Closure Compiler's support for JavaScript= annotation, plus some custom Servoy extensions.
=20See JSDoc Tag= s and Type Expressions below for the supported tags and their synta= x.
=20As mentioned in the intro, the Script Editor in Servoy Developer utilize= s JSDoc to improve the quality of code completion and validation.
=20The Script Editor and Servoy Developer in general also facilitates the c= reation of JSDoc comments:
=20When hovering over a reference to the variable of function somewhere in = the Solution, the tooltip will show the JSDoc for the variable/function.
=20Note= that the Script Editor will always generate a JSDoc comment block with a @= properties tag when saving the Script editor, if no JSDoc comments have bee= n defined. The @properties tag is a tag containing information for Servoy t= o provide proper linking and versioning.
=20The following JSDoc tags are supported in the Script Editor. This means = that the JSDoc tags will be rendered without the "@" sign when hovering ove= r a reference tot he function or variable.
=20The developer can add any custom tag to the JSDoc comment, but besides b= eing shown in the tooltip when hovering over references it will not do anyt= hing.
=20Tag | =20
Syntax & Examples | =20
Context | =20
Impact | =20
Description | =20
---|---|---|---|---|
@AllowToRunInFind | =20
@AllowToRunInFind | =20
function | =20
Determines if the function will be executes = in FindMode when used as an event handler | =20
Custom Servoy JSDoc tag to annotate a functi= on that it can be run if the Form on which the function is ran is in FindMo= de | =20
@author | =20
@author userName | =20
function, variable | =20
none | =20
Indicates the author of the code | =
=20
@constructor | =20
@constructor | =20
function | =20
This will show a different icon on the Scrip= t Outline view. besides that no further impact | =20
| =20
@deprecated | =20
@deprecated | =20
function, variable | =20
Accessing a deprecated variable or calling a=
deprecated function will produce a builder marker in Servoy Developer | =20
Indicates that the function or variable is o= bsolete or has been replaced and should be used anymore. | =20
@example | =20
@example | =20
function | =20
none | Tag allowing to provide some sample code how=
to use the function or variable. Multiline content is possible my includin=
g " | =20
@param | =20
@param {Type} name parameterDescription = | =20
function | =20
Builder markers will be generated in Servoy =
Developer if the function is called with values for the parameters that do =
no | =20
Describe function parameters. | =20
@private | =20
@private | =20
function, variable | =20
Accessing a private variable/function from o= utside the scope in which it is declared will generate a builder marker in = Servoy Developer | =20
Annotates a variable or function as accessib= le only from within the file in which it is declared | =20
@protected | =20
@protected | =20
function, variable | =20
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 acc= essible from within the same file in which it is declared and all files tha= t extend this file | =20
@return | =20
@return {Type} | =20
function | =20
The specified type is used by the build proc= ess to determine the correctness of the code that uses the returned value <= /p> | =20
Annotates the type of the returned value. If the function does not return any value, =
omit the @return tag. | =20
@returns | =20
@returns {Type} | =20
function | =20
see @return | =20
alias for @return | =20
@see | =20
@see seeDescription | =20
function, variable | =20
none | =20
Tag to provide pointers to other parts of th= e code that are related | =20
@since | =20
@since versionDescription | =20
function, variable | =20
none | Tag to provide information about in which ve= rsion of the code the variable or function was introduced | =20
@SuppressWarnings | =20
@SuppressWarnings ([deprecated], [hides], [w= rongparameters], [undeclared]) | =20
function | =20
Stop the generation of builder markers in Se= rvoy Developer for the specified warnings | =20
Custom Servoy JSDoc tag to suppress builder =
markers of a certain type within a function. | =20
@throws | =20
@throws {Type} | =20
function | =20
none | Tag to describe the type of Exceptions that =
can be raised when the function is called. | =20
@type | =20
@type {Type} | =20
variable, inline variable, (function*) =
| =20
The specified type is used by the build proc=
ess to determine the correctness of the code that uses the variable | =20
Tag to specify the type of the value that a =
variable can hold. | =20
@version | =20
@version versionDescription | =20
function, variable | =20
none | Tag to provide information about the version= of the code | =20
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 annotati= ng variables and functions within the globals JavaScript file
=20Type Expressions are used to describe the type and/or structure of data = in the following cases:
=20Use case | =20
Tag | =20
Example | =20
---|---|---|
function parameters | =20
@param | =20
/** | =20
function return type | =20
@return | =20
/** | =20
functions exceptions | =20
@throws | =20
/** | =20
variables | =20
@type | =20
/** | =20
| =20
| =20
| =20
A Type Expression is to always be surrounded by curly braces: {typeExpre= ssion}. Note that when using the Object Type expression variation that star= t and stops with curly braces as well, this results in double opening and c= losing braces.
=20Expression name | =20
Syntax example | =20
Context | =20
Comments | =20
---|---|---|---|
Named type | =20
{Stri=
ng} | =20
@param, @return, @type, @throws | =20
The complete list of available types can be = seen by triggering Code Completion inside the curly braces in the Script Ed= itor | =20
AnyType | =20
* | =20
@param, @return, @type, @throws | =20
| =20
OR Type | =20
{Stri=
ng|Number} | =20
@param, @return, @type, @throws | =20
| =20
REST Type | =20
{...S=
tring} | =20
@param | =20
| =20
Array Type | =20
{Stri=
ng[]} | =20
@param, @return, @type, @throws | =20
| =20
Object Type | =20
{Obje=
ct} | =20
@param, @return, @type, @throws | =20
| =20
Object Type with optional properties =20 | { {na=
me:String, [age]:Number}} | =20
@param, @return, @type, @throws | =20
| =20
JSFoundset type | =20
{JSFo=
undset}1&nb=
sp; | =20
@param, @return, @type | =20
| =20
JSRecord type | =20
{JSRe=
cord}1 | =20
@param, @return, @type | =20
| =20
JSDataSet type | =20
{JSDa=
taSet<{name:String, age:Number}>} | =20
@param, @return, @type | =20
| =20
RuntimeForm Type | =20
{Runt=
imeForm} | =20
@param, @return, @type | =20
| =20
1 the value in between <..> is the datasource notation = that is built up of the database server and tablename: db:/{serverName}/{ta= bleName}
=20JSDoc can be used inside JavaScript code to specify the type of variable= s. This can be necessary if the correct type can't be automatically derived= .
=20An example of such scenario is for example the databaseManager.getFoundS= et() function. This function returns an object of the generic type JSFoundS= et. In most if not all scenario's however, it is known for which specific d= atasource the JSFoundSet was instantiated and the foundset object will be u= sed as such in code, accessing dataproviders on the foundset object that ar= e specific to the datasource. This will result in builder markers, because = those dataproviders are not know on the generic JSFoundSet type. Through JS= Doc casting however, it's possible to specify the type of the foundset obje= ct more specifically
=20/**@type {= JSFoundset<db:/udm/contacts>}*/ var fs =3D databaseManager.getFoundSet('db:/udm/contacts')=20
The difference between Code Completion with and without Type Casting can= be seen in the two screenshots below. whent he Type casting is omitted, th= e offered Code Completion related only to the generic JSFoundset type. With= the Type Casting in place, all the dataproviders of the specific datasourc= e are also available in Code Completion:
=20With Type Casting:
Without Type Casting:
Another example is entries in Objects and/or Arrays: if every entry is o= f the same type, this can be specified on the Object/Array declaration usin= g JSDoc, for example:
=20/**@type {= Array<String>}*/ var myStringArray =3D \[\]=20
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 mor= e generic type can be specified.
=20An example of a generic type would be RuntimeComponent, which is the sup= er type for RuntimeLabel, RuntimeField etc. RuntimeComponent defines all th= e properties and methods that all the other RuntimeXxxx types have in commo= n. When the need arises to call methods or set properties that are specific= to a specific RuntimeXxx type, the generic type can be casted:
=20if (elemen= ts\[1\] instanceof RuntimeLabel) { /**@type{RuntimeLabel}*/ var myLabel =3D elements\[1\] var elementNames =3D myLabel.getLabelForElementName() //Calling method sp= ecific for labels }=20
Type Casting can only be performed on variable declarations. It is not p= ossible switch the type of an already declared variable later in code