Friday, November 23, 2012

What is this cloud thing?

Here are the slides from my UBC alumni presentation on programming for the cloud.



You can also download the demo code that I wrote during the talk here on github.

Thank you all who came. It was a lot of fun to give the talk.

Saturday, November 17, 2012

Lots of beer, pizza, and coding

Lots of beer, pizza, and coding. I'd say that our second Vancouver Eclipse hackathon was a huge success. We had committers from several Eclipse and Eclipse based projects: Mylyn, p2, JDT, Orion, and Scripted were all represented. We had 30 hackers spread across all of these projects. Currently, we have 7 patches that have been accepted into codebases, and three more that are working their way through the submission process.

The hackathon was a great and social way to be introduced into the open-source world and perhaps some of these new Eclipse contributors can become Eclipse committers. If you are interested in holding an Eclipse hackathon (or any hackathon) in your area, feel free to contact me. I now know what works and what doesn't.


Just getting started


All working hard


Nieraj and Leo take a moment to relax


Ian Skerret, flew all the way from Ottawa for us

A big thank you to all the project leads who helped (and are still helping) some newcomers fixing their first bug. And an even bigger thank you to everyone who worked hard and stayed up late, just to do some coding. It was a lot of fun.

For another look at the hackathon and more photos, see the Tasktop blog.

Thursday, November 1, 2012

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.