Problem with Go-To and code-assist for parameter variables when using AMD and a package.json

Hi folks,

I am trying to get code-assist and Go To to work  properly with AMD modules. It works well in most situations, but I am having two problems (I think, I am guessing a bit based on a day of laborous debugging) :

1) The JSDoc @param construct references symbols derived from JSDoc, not using the local names of the AMD defintion callback.
2) Introducing a package.json breaks Go To and code assist for parameters in functions (for parameters referencing those classes/modules that are located  in the same directory as the package.json).

I can live with problem 1, although I have to write modules in a certain way, to make sure that the JSDoc symbols are detected for the correct name.
Problem 2 is harder as I really need to have package.json to allow the build process to work as expected (at least I think so, I am using Dojo1.8.3).

Maybe there is some trick I am unaware of. Here is an example of the situation, in a directory X I have two files, A and B:

define([], function() {
     * @constructor
    var BB = function() {};
    BB.prototype.myFunc = function() {};
    return BB;

define(["./B"], function(B) {
    var b = new B();
    //Both Go To and code assist works here

     * @param {BB} b is an instance of the class B.
    var f = function(bb) {
        bb.myFunc();  //The problem is here

Having only these two files Go To and code assist works:
i) for the 'b' variable as its class is from the AMD callback function.
ii) for the 'bb' parameter to the function f  as the @param indicates that class is BB (I used BB in the B.js file just to show that it is the symbols from JSDoc that is used not the AMD callback variable B).

But, if I add a package.json in the same directory as A.js and B.js, code assist and Go To no longer works.
(NOTE, when you experiment with this you have to change something in the B.js file to trigger the regeneration of symbos that yields the effect in addition to creating the package.json file, similarly if you remove it again.)

I noticed that it does not matter what is inside the package.json, it can be entirely empty. Something is triggered which affects the entire generation of symbols. I tried to disable the node.js plugin in case that was the culprit. I also tried with having a package.json wich correctly names the package:
{"name": "mymodule"} and then use mymodule/BB or mymodule/B in the param tag, but it does not help.

I have run out of ideas how to tackle the problem.

Hope you can help

Comment actions Permalink

Hi Matthias,

thanks for the detailed report! I've logged this issue as
To me, bb.myFunc(); is not resolved even without package.json presence - it's enough to change parameter name in JSDoc from 'b' to 'bb' (i.e. to update the comment to match the actual parameter name) to see the problem. Seems that it only works for you because the param name in comment is egual to var b defined in same function :)

Best regards,

Comment actions Permalink

Ah thanks for your response and creating an issue!

You are right, with the correct variable name in the @param comment the problem is visible without the package.json as long as you indicating the class to be simply BB in the @param.

However, I just observed that if I introduce a package.json and change the @param to indicate x.B instead of just BB (B.js is placed in folder x) it works!

define(["./B"], function(B) {

   //The following JSDoc will contain warnings of the module x and class BB and no .
     * @param {x.B} b is an instance of the class BB defined in the file B.js in the folder x where there is a package.json.
    var f = function(bb) {
        bb.myFunc();  //Problem solved!

Note that it is the name of the file, AMD style, that is used rather than the symbol inside of the file that is used, and, it also seem to handle multiple levels of modules, great!!!!!
On the negative side though, the JSDoc is not resolved, i.e. I cannot Go To the declaration of either x or BB in the @param annotation.

So, now I am really confused, which notation should I use in the JSdoc for the future. To sum it up:

1) @param {BB}                   (detected JSDoc symbol)
2) @param {x.y.B}                ('global' AMD name of module but with dot-notation instead.)
3) @param {B}                      (local scope AMD name of module)
4) @param {x/y/B}                ('global' AMD name of module, same as used in require/define, should support relative paths as well)

There is partial support for (1) and (2):
Choose (1) - Go To and code-assist works in the @params but not for the parameters in the function body.   ==> Issue
Choose (2) in combination with a package.json - Go To and code-assist works on the parameters in the function body but not in  @params.  ==> Issue ????

It seems that there are no support for either (3) or (4) in WebStorm right now.

I am leanding towards using (2) for now and hope that the warnings in JSDoc will go away in a future release of WebStorm. But I wonder if not (3) and/or (4) could be supported as well in the future when the use of AMD increases (as I think it will). This would provide a more uniform way to write AMD modules and document them.
Any thoughts on this?

If you think that (2) is the correct way to proceed write JSDoc, then in addition to the issue already created another issue should be created for the problems with code-assist and Go To for the @params in JSDoc. In fact such an issue is quite important as those who try to write good JSDoc get warnings ("unresolved variable or type") . And given those warnings most developers will  probably not leave them in there and will therefore miss the fact that they would have helped to write the function body (and get less  warnings of the actual code).

Finally, I think (1) and (2) should not be supported simultaneously as it might lead to conflicts between the JSDoc symbols and AMD modules. My tests seem to indicate that they are in fact exclusive, with a package.json only (2) is supported, otherwise only (1). Maybe document this for developers somewhere...

Takeaway message:
Create an issue to better support JSDoc notation according to (2) in combination with package.json (support Go To declaration at least).
Documented somewhere how to write better JSDoc with WebStorm. Something like:

Option A) You have a simple project with a few javascript files:
  i) Organize your javascript files however you wish, but do not have any package.json files anywhere.
  ii) Use JSDoc as much as you like (insert list of supported tags and some example, similar to  B.js above but perhaps without the AMD, note how classes can be marked and methods autodetected based on assignment to the prototype).

Option B) You have a complex project with many modules, e.g. using AMD style definitions:
  i) Always use package.json at each top-level module.
  ii) In all of JSDoc, use module.submodule.subsubmodule to indicate your modules, e.g. @param {vehicles.Car} car.


Message was edited by: Matthias Palmér

Comment actions Permalink

I created an issue for the problem with jsdoc warnings when a package.json is present and using the dot.notation in @params, that is, what I referred to as choice (2) above.



Please sign in to leave a comment.