As of writing, the only IDE that can interpret JSDoc to any reasonable level is Webstorm. So all examples in this article are using the Webstorm IDE.
Simple Type Checking
Parameters types can be defined in the comments of the function. In this example we are annotating the x value being passed into the popup() method :
Now we are passing in a number :
Notice the squiggly line underneath the number 12345?
If we hover our mouse over the squiggly line, we should see a tooltip telling us what the problem is :
That’s pretty neat! Type checking at last!
The @param JSDoc annotation allows us to say what we want passed into a function. We can also use this annotation on other primitive types such as number and boolean. Let’s have a look at how we can use the @param annotation on some more interesting objects.
Arrays and the Type Annotation
In the following example we are passing an array into a function :
In the above we create two types of fruit, and make an array for each of them. By using angular brackets, we can define the type of the array being passed in (Array.<Apple> )
Using the @type annotation we can annotate a variable. In our array example we are stating that we want out element to be of type Banana. As the second array being passed in is of type Apple, our JSDoc annotation is being infringed and we get the squiggly gray line again.
At the time of writing Webstorm does not support the JSDoc checking of the inner type of an array when being passed to a function (See the comments).
Parameter annotations on arrays can also help in code completion.
The JS compiler knows the element in an array is of type apple and shows the apple elements in the drop down list. This is unbelievably helpful!
In the following example we are using the @param tag annotation again. Here we are annotating an object literal with two fields: name, and email which are both strings :
In the method body, a variable is assigned to the user.name. This variable has to be of type string, and matches up with the name type being passed into the method.
The following two examples show where the IDE complains and the squiggly gray lines start appearing again :
The @param annotation expects a number but we are passing in an array. Our @type annotation declares a variable to be string, but out @param says our user object can only be number.
In this case we are trying to treat one of the string fields as a number :
We can even document an array of literals.
In the following example the IDE will complain about the variable i being assigned to a string :
Again, code completion is enhanced. The IDE deals with the fields in an object literal :
Returns can be annotated too.
In this example the IDE indicates there is a problem on the line where x is assigned the return value.
In this example the assignment is correct, however there is now a problem with the return statement. The IDE picks up on what is happening inside the function is incorrect.
Finally this example has everything working correctly :
The IDE will complain at exactly this line : processFruit(new Orange())