How to create Javascript API Stubs to get the best out of JS code completion

We have a very big Javascript API that uses a custom "classical" framework. We are huge fans of Jetbrains products and would like to recommend to our customers (the users of the library) the Jetbrains products for working with our API. So far we have had a little success in getting the JS code completion to work with our library. We have generated a Javascript Stub API that uses protoype syntax and JSDoc annotation for the documentation in order to help the code completion engine better understand our API. This works great in parts but seems to fail in other situations.

We would like to get feedback from Jetbrains and possibly the community who have worked with complex APIs on how to *ideally* create and annotate the stub syntax so that we can get the most out of the code completion.
Note that the information doesn't have to be restricted to stubs, it's just that we have created stubs since our classical framework cannot be parsed by IDEA (and I don't expect it to be able to). The same solution could be applied to any javascript libraries.
I was not able to find information about this topic available on the internet. However from the navigate to defination feature I can see that at least in IDEA there are stub .js files bundled into the IDE that seem to work well.

Any insights into this would be greatly appreciated.

8 comments
Comment actions Permalink

Hello, Sebastian. Thanks for kind words!

Completion work as expected(i.e. show only variable properties which is actually belongs to it) when engine knows "class" of the variable before dot. It is inferred correctly in many cases, but not in all. Please provide your api usage example when completion doesn't work as expected.
Bundled .js stub files are actually javascript libraries, which could also be created by user. Have you looked at http://www.jetbrains.com/phpstorm/webhelp/configuring-javascript-libraries.html ?

0
Comment actions Permalink

Hi,

just for the reference - this is the first issue I have extracted from our usecase:

http://youtrack.jetbrains.com/issue/WI-11259

{code}

/**
* @constructor
* @class {test.A}
*/
test.A = function() {};
test.A.prototype={
    /**
     * b property
     * @type {test.B}
     */
    'b':null
};


/**
* @constructor
* @class {test.B}
*/
test.B = function() {};
test.B.prototype={
    /**
     * a property
     * @type {test.A}
     */
    'a':null
};


{code}

In this case completion does not work as expected:

{code}

var inferredB = new test.A().b;
var b = new test.B();

{code}

completion works perfectly for "b" but not for "inferredB".

This is a very basic feature and not having it work as expected makes programming against a larger API very difficult, if not impossible.
But maybe I am doing something wrong, here....

Thanks - Sebastian
0
Comment actions Permalink

We have this usecase where our Javascript object can implement multiple interfaces or extend multiple traits. So there can be a normal prototypical inheritance (instanceof in Javascript) and also types are guaranteed to implement a certain interface, similar to the SVG element Javascript API.
However it seems the code completion can only currently deal with single inheritance (via @extends) and does not understand interfaces. Neither @extends/@augments/@implements seems to work as described here http://youtrack.jetbrains.com/issue/WI-11298 .

Without this feature code completion often yields only a subset of the possible methods that can be called and code is underlined as "not assignable" very often.

Is there a way to make the IDE understand interfaces? The only workaround I know would be to copy the interfaces to the prototypes of their implementations - however our javascript *stub* file is already 120k lines of code and copying the interfaces to their implementors would probably bring that size easily to 200K lines. I need to tweak the idea.properties file already to work with the "small" version, so I would really like to not go that route.

0
Comment actions Permalink

Currently multiple inheritance is not supported, but it is planned to 5th version. See IDEA-86043 and related issues. Now I can only suggest you to wait for the 5th version EAP.

0
Comment actions Permalink

Ah cool! I did not see this issue, possibly because I was looking for open tickets. Good to know that this is coming some time in the future :-)

0
Comment actions Permalink

I have another problem with the jsdoc documentation. I want to create jsdoc document for some methods of standard library Mootools.
But my jsdoc are not displayed:

/**
* Returns true if every element in the array satisfies the provided testing function
* @param   {Function}  fn    The function to test for each element.
* @param   {Object}    bind  The object to use as 'this' in the function
* <br>@example: <pre>
*  var isAllBigEnough = [10, 4, 25, 100].every(function(el, i) {
*    return el > 20;
*  }); // false
* </pre>
* @return  {Boolean}
*/
Array.prototype.every = function(fn, bind) {};

[].every()
Press Ctr+Q on this method `every` , documentation is not displayed!
Why?

0
Comment actions Permalink

Works for me, but two possible methods are suggested to choose when Ctrl-Q is invoked. Is this method resolved(Ctrl-click)? What version do you use? Please create an issue in our issue tracker.

Regards,
Konstantin

0
Comment actions Permalink

Im use PhpStorm 5.0.4, Buil: 121.390.
Example, method `every` not works: http://i.imgur.com/WmZE4.png
But custom jsdoc for `each` - works: http://i.imgur.com/bZtyB.png
On `Ctrl-click` also does not show the link to the my documentation.
OS: Linux 3.5.0-19-generic #30-Ubuntu SMP Tue Nov 13 17:48:01 UTC 2012 x86_64 x86_64 x86_64 GNU/Linux

This new issue.

0

Please sign in to leave a comment.