JSDoc for function parameter properties + WebStorm

Question

What is the correct JSDdoc declaration for company being a String in the code below?

 fetch('https://api.github.com/users/mdo').then(res => res.json()).then(res => { console.log(res.company); }); 

I use WebStorm and it understandably underscores company as an Unresolved variable :

if I add

/** @namespace bogus.company **/

anywhere in the file, WebStorm is happy, but that doesn't make sense:

Is this a bug in WebStorm, or am I missing something about how JSDoc declarations are supposed to work?

Is JSDoc even supposed to be used for this use case?

Answer 1

If you check the inspection for unresolved javascript variable there is a Report undeclared properties as error option that you could uncheck.

I like to do something like this:

/**
 * @param {Object} res
 * @property {String} company
 */
function myOutput(res) {
  console.log(res.company);
}

fetch('https://api.github.com/users/mdo')
  .then(myToJson)
  .then(myOutput);

But for small anonymous functions I wouldn't even bother. It's a weak warning so turn the inspection off or learn to live with it, I'd say. It's possible to cram in /** @param {*} something */ in anonymous functions as well, but often it only serves to reduce readability.

Another option is to make a dummy file soomething.js somewhere under your content-root with an anonymous function like:

(() => {
  return {
    "github-users-response" : {
      "company" : "sample"
    }
  }
});

And now webstorm will figure that company actually is defined in your other files. You can even put it in a different content-root if you want to keep it separate from your project.