JSDoc *in WebStorm* and (ES 2015) promises?

Does Webstorm (and I'm not asking about JSDoc in general) have a format that it accepts to document "Promise" return values?

Second question, apart from pointing to http://usejsdoc.org/index.html is there an overview anywhere about how WebStorm determines types? I'm regularly surprised by what works, or more often what doesn't, incl. in the latest EAP.

For example, I'm looking at a file where I'm using promises heavily, and type detection incl. what a chain of promises hands over from one `.then(...)` to the next one in the chain does not seem to work at all. Is this just not implemented yet? An overview over what works (and where WebStorm gets its information) would be nice. For example, how about a tool inside WebStorm that lets me inspect its internal information that it gathered from my files, so that I can see first-hand how type-deduction works? It might allow me to either fix my files so that it works better, or to know if it's time to submit a bug report.

11 comments
Comment actions Permalink

Enabling 'ECMAScript 6' predefined library in Settings/Languages & Frameworks/JavaScript/Libraries should make WebStorm recognize Promise type (normally this library is enabled automatically on changing javascript language version to 'ECMAScript 6' or 'JSX Harmony'). If this doesn't work for you, can you provide a code sample that shows up the issue?
as for JSDoc support,  we are trying to support mix of tags from different standards, so users  won't be forced to rewrite their documentation code to work well with  WebStorm. Google Closure (https://developers.google.com/closure/compiler/docs/js-for-compiler) is supported the most completely, including  type syntax. JSDoc3 is partially supported for now.

0
Comment actions Permalink

The problem isn't the promise type - but the type of the `resolve()`, the argument to the function in `.then(...)`.

0
Comment actions Permalink

Please provide a code sample that shows up your issue - what you are trying to document and how


0
Comment actions Permalink

Are you aware of how promises work?

This is the issue:

http://stackoverflow.com/questions/13104411/how-to-specify-resolution-and-rejection-type-of-the-promise-in-jsdoc

https://github.com/jsdoc3/jsdoc/issues/509


A function returns an object of type "Promise" - that is as it always is in Javascript. That part works, there is nothing special about it.

However, promises at some point are resolved or rejected - with a normal Javascript value. Or another promise. I use the "then" (or catch) method on a promise and hand it a function - which is called when the promise is resolved. The type that these callback functions get, i.e. the value promises resolve with, does not seem to work in WebStorm.

1
Comment actions Permalink

Thanks for details, but it's still not clear what format you are using (as there are no JSDoc standards for documenting promises, and WebStorm doesn't have its own formats for this)

I use the "then" (or catch) method on a promise and hand it a function - which is called when the promise is resolved. The type that these callback functions get, i.e. the value promises resolve with, does not seem to work in WebStorm.


what doesn't work namely? Code sample, please

0
Comment actions Permalink

> but it's still not clear what format you are using

That was my question: What _should_ I use?


> (as there are no JSDoc standards for documenting promises, and WebStorm
> doesn't have its own formats for this)

So it isn't possible?

I don't care about the JSDoc "standard" (that is a very loaded word), I only care what works in WebStorm. People have been proposing and using different ways to document promises, see the links I posted. Stuff gets used all the time even though some "standard" has not (yet) been agreed upon. It's not as if there's only JSDoc, sometimes other things (Google closure compiler?) seem to be supported - it's hard to tell what exactly, there is no page that says "this is 100% what we support". Yes I found the page that linked to the JSDoc page I mentioned, but it seems that other things from, I think, Google Closure Compiler are supported as well? I can't really tell!

0
Comment actions Permalink

WebStorm doesn't have any particular requirements for documenting this stuff (and not only this). We just try to support existing standards... I can tell for sure that tags that aren't yet a part of any standard (like @promise) won't work. But you can try other ways (like @typedef, etc)

0
Comment actions Permalink

> WebStorm doesn't have any particular requirements for documenting this stuff (and not only this).
> We just try to support existing standards...


Well that is the question: What exactly do you support? Apart form the promises, where the answer seems to be a simple "No". Even if you made a statement like "we support exactly and not one thing more or less than http://usejsdoc.org/index.html" is useless, because the devil is in the details and _how_ exactly the parsing and type information gathering works would be nice to know.

For example, when I define a type using @typedef, is it available everywhere or only in files including it? The latter would be inconvenient to say the least, because a module could get a parameter of a type defined in a module that it does not include, via a 3rd module.

1
Comment actions Permalink

As Mörre asked, what specific JSDoc annotations does WebStorm support?

I have not been able to find any documentation that provides any detail. I've spent dozens of hours trying to get WebStorm to correctly identify our code. The only thing we can do it a bunch of trial and error which is painful without any tools or docs that could help us.

0
Comment actions Permalink

Hello,

 

With ECMAscript 6 enabled it seems to be working:

However I cannot currently get it to work in a large project, something is confusing Webstorm, tried all kinds of stuff, still no luck.

 

It would be nice if Webstorm could infer the type of chaining then calls, currently does not seem to be working:

 

vscode seems to be working as expected:

3
Comment actions Permalink
/** @type {Promise<string>} */
let p = Promise.resolve("some string")
p.then(x => x.) // doesn't understand type


let p = Promise.resolve("some string")
p.then(x => x.) // understands type

Seems webstorm is confused by the explict Promise<*> syntax. In both cases the quick documentation on p shows `Promise<string>`

 

WebStorm 2019.3
Build #WS-193.5233.80, built on November 25, 2019
Non-Bundled Plugins: Activity Tracker, Key Promoter X, Shifter, com.intellij.lang.jsgraphql, com.mnw.tabmover, com.potterhsu.jsonviewer, com.ultrahob.zerolength.plugin, net.vektah.codeglance, org.jeto.taskfocus, uk.co.ben-gibson.remote.repository.mapper

0

Please sign in to leave a comment.