How to properly define JSDoc for an object with methods?

Plop,

This question is on the border between general best practices on JSDoc and WebStorm indexing (and auto-completion) on the topic of type definition.

I have an object fooEngine which has a method start, a method pause, and a property state. The methods have no parameter.
I'm trying to document that properly. I would prefer to define a type. Finding little to no documentation about @typedef, I had to make a lot of failures... I used the following code:

/**
* Your classic Foo Engine
* @typedef {Object} Foo Engine
* @method start Starts the Foo Engine
* @method stop Stops the Foo Engine
* @property {String} state Current state of the Foo Engine
*/

/**
* My own Foo Engine
* @type {FooEngine}
*/
var fooEngine; //Will be used for all tests


First try, first issues: I can't auto-complete to the methods (fooEngine.start, fooEngine.stop).
New try this time using @property {Function} instead of @method:

/**
* Your classic Foo Engine
* @typedef {Object} FooEngine
* @property {Function} start Starts the Foo Engine
* @property {Function} stop Stops the Foo Engine
* @property {String} state Current state of the Foo Engine
*/


It works somewhat okay, I can now see the methods auto-completed, but they are not auto-completed as functions:

fooEngine.start //No parenthesis!


And I can't see the FooEngine documentation:
http://puu.sh/gXL9T/69ff06153e.png
So how would I go to write such a doc, to be compliant with the best practices (wherever they are written, and if you have any data on that I'm eager to hear about it!) and of course compliant with WebStorm and its indexing?
Due to the lack of data I have troubles figuring out how I should write the doc in the first place...

Thanks.

PS: And by the way, what if the methods start and stop had parameters? How would I go about defining them?
PPS: Demo file linked, but you can just copy the two blocks of code.



Attachment(s):
fooEngine-JSDoc.js
4 comments
Comment actions Permalink

I can suggest using

/**
* Your classic Foo Engine
* @typedef {Object} FooEngine
* @property {function(string, boolean)} start Starts the [Foo/Bar] Engine
* @property {function} stop Stops the [Foo/Bar] Engine
* @property {String} state Current state of the [Foo/Bar] Engine
*/

/**
* My own Foo Engine
* @type {FooEngine}
*/
var fooEngine;


completion will work, as well as quick doc (at least it works for me in WebStorm 10). You won't, however, get parentheses auto-completed:(

0
Comment actions Permalink

Neither will I get the parameters auto-completion...

And when trying to get the documentation for FooEngine, it still says "No documentation found".

Dang it. I want to define clear, beautiful, elegant fracking objects and abstractions and stuff!

1
Comment actions Permalink

Exactly my problem. Everything defined in a completely standard node.js module structure and code, and what for? WebStorm advertises autocompletion and code support (CTRL-Q, for example) but it's useless, much of that stuff does not work. And then I look at their blog post with the feature discussionfor WebStorm 11 where they again want to add ever more and ever more exotic things -- no word about fixing the basic stuff. Yes I have filed bug reports already, several, about not that exact topic (but related) -- but since there is not much progress on them I'm not keen on producing ever more bug reports that developers, working on all those new shiny features?, have no time to follow up on?

Here's a suggestion: How about a github demo project to show us how/which features of autocompletion and code help popups are supposed to work? Incl. correcct  JSDoc according to WebStorm. So that we can use that as reference and know which features are missing, which are a bug if they don't work, which are because WebStorm expects a different project sturcture or JSDoc, etc...

4

Please sign in to leave a comment.