JSDoc is more than just documentation (in Scripted)

Recently, we released the Scripted editor for editing your JavaScript. It's still early stages, but our focus on a light-weight and semantically aware editor already has some compelling features. In this blog post, I'll show you how you can use JSDoc in your JavaScript files to provide Scripted with some inferencing help. Since Scripted uses the Orion editor, most of this JSDoc support is also available in Orion.

There are many flavors of JSDoc and there is no standard, but the Google Closure Compiler uses a style that is well-documented, self-consistent, and complete. We use Doctrine as the JSDoc parser, which has a complete understanding of the JSDoc annotations of the Closure Compiler.

Currently, Scripted recognizes a subset of JSDoc tags:

• @type {type-sig} {optional-doc} specifies the type of a variable declaration
• @param {type-sig} {param-name} {optional-doc} specifies the type of a function parameter. Parameter annotations are not positional. They must correspond to an actual named argument of the function.
• @return {type-sig} {optional-doc} specifies the return type of a function

The docs for the Closure Compiler specify many kinds of type signatures. Only a subset are relevant to and supported in Scripted. Scripted recognizes:

• Simple types, eg- {Window}, {boolean}, {Boolean}
• Record types, eg- {{myNum: number, myObject}}
• Function types, eg- {function(arg0:string,arg1:boolean)}
• Function return types, eg- {function():number}

And of course, type signatures can be combined to produce more complex signatures. The built-in types boolean, number, string, and object can optionally be capitalized, this breaks from the semantics of the closure compiler, but provides more flexibility to programmers. Other kinds of signatures are tolerated, but do not affect the inferred type.

Examples

With this information, we can start showing some examples. Scripted uses typing information for hovers, navigation (e.g., CTRL+Click to navigate to definitions), and for content assist.

Simple @type

Here is a simple JSDoc comment to define a string variable:

Record types

Using a record type signature, you can define the type of an object literal:

Functions

You can specify that a variable is a function, as well as include its parameter names and return types (parameter types are currently ignored for function type signatures). It looks like this:

If you want to declare the types of function parameters, then you should be using the @param annotation, like this:

User defined types

User defined types are recognized as well:

Union types

One possible point of confusion is with union types. They are interpreted by Scripted as whatever the first signature is. So, in the following is interpreted as a string:

Node support

And finally, Scripted's JSDoc support can be combined with its dependency analysis to infer types defined in other modules. This is extremely helpful for node projects where the use of callbacks can obscure the parameter types. In the following example, by specifying the types of the req an res parameters, you can get some meaningful content assist for them:

What's next

There are some more interesting cases that we should handle. A common idiom in JavaScript is to declare constructors using qualified names. Libraries like Dojo and Ext JS. For example, you can define a class name in Ext JS like this:

Ext.define('scripted.Widget', { ... });

And in Dojo:

var Widget = dojo.declare('scripted.Widget', [], { ... });

We could accomplish this using the @typedef annotation or possibly the @constructor annotation.

Additionally, the @lends annotation provides a nice way to specify options and configuration for constructing types and will likely make it into an upcoming version of Scripted.

So?

Using JSDoc in your JavaScript files is a good way to give some extra help to the inferencer, which often has trouble recognizing some of JavaScript's more dynamic features. Scripted is still in its early stages, and is moving ahead quickly. We like feedback. You can send a message to the Google group and fork us on Github.