Servoy 6.0 alpha 4

[jcompagner]

that one is not supported (yet)
but also i am still not really for that one to support that
i really dislike that construct. Because what does that mean? So suddenly code completion and validation must allow both types in that function for that argument
But 1 of them is just illegal and will result in wrong code.
it is way better to split that one into 2 arguments.

[rossent]

Hi all,

On several occasions, we experienced an issue where after modifying the existing JSDoc comments for functions in order to resolve warnings in Servoy 6a4 and saving the changes, the JSDoc content is wiped off and replaced by the generic:

/**
* // TODO generated, please specify type and doc for the params
* @param {Object} paramName
* ...
*/

In those cases the Servoy Developer gets into some sort of an infinite loop where the @properties UUID constantly gets re-generated and the .js file is constantly being modified and saved (the toolbar "Save" buttons constantly "blink" from enabled to disabled state and the file "Undo" history is lost due to the numerous auto changes and saves). The Developer is not "frozen" and by manually making any change to the .js file "kills" the infinite loop but all changes made to the JSDoc comments are gone. In some cases, the auto-generated JSDoc overlaps with the edits which the programmers are doing in the moment resulting in invalid comment section altogether. We cannot reproduce this issue at will but multiple developers experience the same on different machines.

Has anyone else experienced something similar? Is Servoy aware of this issue and are there any fixes for it? This will be a major trouble for anyone who tries to convert existing code from Servoy 5 (with some already existing JSDoc comments) to Servoy 6 .

[rossent]

that one is not supported (yet)
but also i am still not really for that one to support that
i really dislike that construct. Because what does that mean? So suddenly code completion and validation must allow both types in that function for that argument
But 1 of them is just illegal and will result in wrong code.
it is way better to split that one into 2 arguments.

I disagree with you. Here are my reasons:
- Such construct is perfectly valid for JavaScript and there are multiple cases where even the Servoy methods are using it. Its meaning is the same as "method overload" in other languages, but JavaScript being a dynamic language allows the "overload" to be handled within the same method.
- The limitation which you are describing is not of the JavaScript language, but of the Servoy tool - for example the Google JSDoc-Toolkit supports it without a problem
- If inside the function, specific code applies to one of the supported types, we could use the /** @type {Type} */ tag to give the code completion a hint of what the code actually means. I have no issue if this is a requirement in order to support the multiple types @param tag.
- Applying some restrictions to new code being developed with the tool due to its limitations perhaps is OK, but I have no justification for such things when I need to refactor 200000 lines of existing code (this is how much we actually have!) to work around the tool limitation. The refactoring in this case cannot be automatic since it requires a new argument to be added to the method signature and the decision of which one to be used in every usage must be done by the programmers.

Hopefully this helps you in your decision to add support for this construct.

[rossent]

Hi all,

When specifying method arguments which are custom objects, we can use the @param tag like the one below to specify the different properties of the argument object:

@param {Object} customerArg - customer arguments object
@param {String} customerArg.name - the name to use
@param {Number} customerArg.age - the customer's age to use
...


Can something similar to this approach be used for the @return tag as well? We have multiple cases where the functions return custom objects and would like to document their properties. I guess, the best way to achieve this will be to create custom "classes" or "types" for the return objects and use those as the type of the @return tag. However, I would like to explore all possible options before deciding which approach we should use.

Any comments or suggestions on this are greatly appreciated!

[jcompagner]

On several occasions, we experienced an issue where after modifying the existing JSDoc comments for functions in order to resolve warnings in Servoy 6a4 and saving the changes, the JSDoc content is wiped off and replaced by the generic:

In those cases the Servoy Developer gets into some sort of an infinite loop where the @properties UUID constantly gets re-generated and the .js file is constantly being modified and saved

if you somehow have a trigger when that happens that would be great.
I will try to reproduce this myself.

[jcompagner]

I disagree with you. Here are my reasons:
- Such construct is perfectly valid for JavaScript and there are multiple cases where even the Servoy methods are using it. Its meaning is the same as "method overload" in other languages, but JavaScript being a dynamic language allows the "overload" to be handled within the same method.
- The limitation which you are describing is not of the JavaScript language, but of the Servoy tool - for example the Google JSDoc-Toolkit supports it without a problem
- If inside the function, specific code applies to one of the supported types, we could use the /** @type {Type} */ tag to give the code completion a hint of what the code actually means. I have no issue if this is a requirement in order to support the multiple types @param tag.
- Applying some restrictions to new code being developed with the tool due to its limitations perhaps is OK, but I have no justification for such things when I need to refactor 200000 lines of existing code (this is how much we actually have!) to work around the tool limitation. The refactoring in this case cannot be automatic since it requires a new argument to be added to the method signature and the decision of which one to be used in every usage must be done by the programmers.

But if you then want to do you own casting then just do

@param {Object}

and inside the function you do:

@type Number

when you use it as a number..

jsdoc toolkit doesn't really do anything with it. But in dltk we need to give that parameter 2 types and also check all calling methods for those 2 types, thats quite some work.

Also a second approach would be to use the thing you specified below:

@param {Object} customerArg - customer arguments object
@param {String} customerArg.asastring- the name to use
@param {Number} customerArg.asanumber - the customer's age to use

[jcompagner]

Can something similar to this approach be used for the @return tag as well? We have multiple cases where the functions return custom objects and would like to document their properties. I guess, the best way to achieve this will be to create custom "classes" or "types" for the return objects and use those as the type of the @return tag. However, I would like to explore all possible options before deciding which approach we should use.

we are looking into something like:

@return {{astring:String,anumber:Number}} My return object with a string and number argument.

the only thing is you can't document the actual property itself.

[rossent]

Hi all,

What is the correct way to document the custom "types" in Servoy so the code completion works correctly and we do not get unknown type related warnings?
The attached solution contains some sample code along with the warnings which we are getting. In this particular case, we use a separate form as "container" for the custom type, however that same happens if we try the global scope (i.e. CustomType = function(...){...};) - in that case there is the added warning for using an "undeclared variable" which is OK (ideally, there should be an option to turn off individual line warnings)

Here is the scenario:

In form named "obj_lib" we define a function which is the constructor for the custom type/class like:

Code: Select all

/**
* @constructor
* @param {String} _name some description
* @param {Number} _age some description
*
* @properties={typeid:24,uuid:"386B4857-1672-4F01-AEA1-229BEC001A95"}
*/
function CustomType(_name, _age)
{
    /** @type {CustomType} */
    var _parent = null;
    this.name = _name;
    this.age = _age;
      
    //special case when we use the third argument to specify the parent
    if(arguments.length > 2)
    {
        var _p = arguments[2];
        if(_p instanceof CustomType)
        {   
            _parent = _p;               
        }           
    }

    /**
    * @return {String}
    */
    this.prettyPrint = function()
    {
       //here code completion for "this" does not work 
       //"this" is not seen as CustomType
       return 'Name: [' + this.name + '] - Age: [' + this.age + ']'
   };       

    /**
    * @param {String} _childName
    * @param {Number} _childAge
    * @return {CustomType}
    */
    this.createChild = function(_childName, _childAge)
    {
       //this works without any warnings
       return new CustomType(_childName, _childAge, this);
    }
   
    /**
    * @return {CustomType}
    */
    this.getParent = function()
    {       
       //here CustomType is not recognized;
       //getting warning: "Function <anonymous> declares CustomType as type but returns Object"
      return _parent;
    }
}


When using the custom type in another form:

Code: Select all

/**
* @return {forms.obj_lib.CustomType} <- this produces the warning "Function prepareObject declares forms.obj_lib.CustomType as type but returns forms.obj_lib.CustomType"
*
* @properties={typeid:24,uuid:"04A231B2-AC12-4B17-9C42-F80F19E49272"}
*/
function prepareObject()
{
   //this extneds correctly the CustomType and adds the newMethod to it
   //however there is a warning: "The static property Function.prototype should be accessed in a static way"   
   forms.obj_lib.CustomType.prototype.newMethod = function(){application.output('new method');};
   
   //the object instance is created correctly
   var _parent = new forms.obj_lib.CustomType('The Parent', 42);
   
   //this works at runtime, however at design time produces the warning: "The function newMethod() is undefined in this script"
        //basically, anything added through the prototype is not reflected on the Intelisense
   _parent.newMethod();
   
   //the code below works and there are no warnings
   var _child = _parent.createChild('The Child', 16);
   application.output(_child.prettyPrint());
   
   return _parent;   
}

/**
* @properties={typeid:24,uuid:"5D4ED946-3CEB-4E9C-9B20-E4B89385041A"}
*/
function useObject()
{
   //this works and there are no warnings
   var _parent = prepareObject();   
   application.output(_parent.prettyPrint());   
   doSomething(_parent);
}

/**
* @param {forms.obj_lib.CustomType} _person <- this produces the warning: "Unknown type forms.obj_lib.CustomType"
*
* @properties={typeid:24,uuid:"D1C0AB55-39A0-4506-8DE1-AB3BD60DE08F"}
*/
function doSomething(_person)
{
   //this works at runtime, however at design produces the warning: "The function prettyPrint() is undefined in this script"
        //since the custom type is not recognized, the code completion for _person does not work at all
   application.output(_person.prettyPrint());
}


Any ideas on this are more than welcome!

[rossent]

What is the correct way to document the custom "types" in Servoy so the code completion works correctly and we do not get unknown type related warnings?
...

The issue with extended methods and properties not being supported by the code completion and code analysis applies also for example if mod_datejs is used - none of the added class or instance methods are visible which is a pity. Developers have to refer either to the source code or some outside reference materials for the correct method names and used arguments, and after that the code analysis still shows up invalid warnings/errors. What will it take to allow the tool to support those cases and provide as much as possible automatic assistance to the developers? For example, the IntelliJ IDEA JavaScript editor handles these cases, so obviously it is technically possible to have such support regardless the dynamic JavaScript nature. Servoy 6 is already much, much better from the version which we started to use it and we greatly appreciate all the efforts which the Servoy team has put into this product. But as a great tool/platform it will always be compared to the best out there and the developers would always want all the bells and whistles which make their daily work easier.

[jcompagner]

Xxxx.prototype.yyy = function(){}

will not be supported in the ide. this is something that just can't be done, it is completely dynamic.

For example you could add your prototype method in function somewhere in a global.js file in some kind of module
and later on in a form.js file in another module expect to have it there. That is just something we just don't know.
Thats only there are runtime

Because it is pretty dynamic the call to yyy function that generates the warning can be circumvented by using it dynamically

myobject['yyy']()

I will also look at the jsdoc custom type problem. Code completion/Type Inferencer knows what you are doing so thats why it works for them
problem is that we currently don't really have support for "package" type scopes, so with a "package" prefix.

[rossent]

Hi all,

On several occasions we experience the issue where after adding/modifying JSDoc comments, the TAB key stops working in the Script Editor. Have not isolated what changes exactly cause this issue but there are some indications that perhaps adding/modifying /** @type {Type} */ inline comments have something to do with this. When the issue occurs, pressing the TAB key does not indent the source code line, however SPACE still works.

Some additional info: in our case we use the default setting to insert spaces instead of tabs and a customized formatting template which was working fine in 5.2.6

Has anyone else experienced this and are there any workarounds?

[rossent]

Xxxx.prototype.yyy = function(){}

will not be supported in the ide. this is something that just can't be done, it is completely dynamic.

I completely understand the technical difficulties involved in supporting this.
How about if providing such support requires that these xxxx.prototype.yyy = function(){} extensions (or even the custom classes/types) are limited to specific .js files and/or these .js files have to be "registered" within the Servoy Developer (this way you will know the code from which files should be "parsed" at design time to extend the code-completion)?
This will be a perfectly acceptable option for us and is the approach used by some other JavaScript editors to work around the dynamic nature of the language.

[jcompagner]

ok i have found a way to resolve this:

Code: Select all

/**
* @param {forms.obj_lib.CustomType} _person
*/
function doSomething(_person) {
   application.output(_person.prettyPrint());
}


the jsdoc type checker does find that now and also code completion works.

[rossent]

It might be needed to enble displayTags on the element to process the titleText at all outside tableview

In a Record View, this does not work regardless the displayTags setting.
In Table View, the links are displayed only if no label is associated with the HTML_AREA element (using the labelFor property), however even when displayed, the links are really not "clickable" (clicking on any of them results in the standard column header click).
I really am having a hard time understanding how exactly this feature is intended to be used. Can someone provide a sample solution for this?

[rossent]

Any update on when the next alpha release of Servoy 6 can be expected?