Is this a bug or a feature - the treatment of JSDoc ! (not null)

In the past couple of days I've just become aware of the ability to define method params and returns in JSDoc such that you can indicate that they can be null (?) or must not be null (!). Because I've just become aware of this element of JSDoc syntax, I'm just going through the process of refactoring some of my JSDocs to include ! and ?.

I've noticed something I did not expect in WebStorm in its interpretation of these symbols and I'm not sure if it is a bug, too broad an interpretation of how this JSDoc syntax should be applied, or if the WebStorm developers have implemented it correctly.

Here is a contrived example (the text in bold is not part of the code, it's part of this post),

/**
* @param {!String[]} myParam (let's call this NonNullDeclaration1)
* @return {!String} (let's call this NonNullDeclaration2)
* @throws {String} A message if the above contract is not adhered to.
*/
window.myFunction = function(myParam) {

var myVariable = null;

if(myParam == null) { (WebStormComplaint1)
throw 'Hey! myParam cannot be null';
}

if(myParam.length > 0) {
myVariable = myParam[0];
}

/* Might do some other stuff here. */

if(myVariable == null) {
myVariable = 'Hello';
}

return myVariable; (WebStormComplaint2)
}

The purpose of NonNullDeclaration1 is to inform user's of the API (via reading the generated JSDoc, reading the JSDoc comments in the code, or editing their code to call myFunction in their JSDoc aware IDE) that myParam must not be null. In response to NonNullDeclaration1, I expect WebStorm to alert the user if they write code that attempts to call myFunction and pass in a value of null for myParam. WebStorm does that correctly. But WebStorm also does something I did not expect - it issues WebStormComplaint1, which is basically a complaint related to comparing myParam to null - because, in WebStorm's mind, that variable cannot be null. I think this is incorrect behaviour on WebStorm's part. Sure I've declared via JSDoc that myParam must not be null, but that just tells callers that they must not pass null. Surely it doesn't place restrictions on what I can go on to do with that parameter in the function body? Additionally, the declaration of not-null is a commenting construct, not a coding construct; user's of my API can still (on purpose or by mistake) pass a value of null for myParam. It is the responsibility of my code (in myFunction) to properly check for and respond to that error condition - the use of JSDoc doesn't mean we suddenly start writing less robust code, surely? Bottom line, imo, WebStorm should not complain when I compare myParam to null.

The purpose of NonNullDeclaration2 is to inform user's of the API (via reading the generated JSDoc or reading the JSDoc comments in the code) that the function will not return null. In response to NonNullDeclaration2, I don't expect WebStorm to alert anyone to anything, it is purely a commenting construct. However, in response to NonNullDelcaration2, WebStorm issues WebStormComplaint2, which is basically a complaint relating to initializing myVariable with a value of null. In other words, WebStorm is complaining that I chose, at one point in time, to set the variable to a value of null then went on to use that variable as the return for a function that is declared not to return null. Frankly, it simply isn't any of WebStorm's concern what values this variable may have had prior to its final value. Perhaps if it knew for sure that myVariable was definitely null when it was returned it could complain. But it should not complain if the variable that is eventually used for return was once set to null, surely? Bottom line, imo, WebStorm should not care if I give myVariable a value of null prior to return (unless, perhaps, if it knows for sure that myVariable is still null when I return it).

So, that's my case. What do you think? Is WebStorm correct in issuing complaints 1 and 2 described above?

Cheers.

Please sign in to leave a comment.