Closure: The Definitive Guide

Chapter 2. Annotations for Closure JavaScript

The Closure Library code base is full of comments, some of which are specially formatted so they can be processed by the Closure Compiler. Understanding these annotations is essential to reading and writing Closure code, which includes the examples in this book. This chapter introduces the JSDoc tags and type expressions that can be found in the comments in Closure code. Google maintains its own documentation on these two topics at http://code.google.com/closure/compiler/docs/js-for-compiler.html.

JSDoc Tags

Most developers’ initial reaction to the Closure Library is that the source code is verbose, particularly with respect to type information. Consider the following definition of the goog.bind function in Closure’s base.js:

/**
 * @param {Function} fn A function to partially apply.
 * @param {Object|undefined} selfObj Specifies the object which |this| should
 *     point to when the function is run. If the value is null or undefined,
 *     it will default to the global object.
 * @param {...*} var_args Additional arguments that are partially
 *     applied to the function.
 * @return {!Function} A partially-applied form of the function bind() was
 *     invoked as a method of.
 */
goog.bind = function(fn, selfObj, var_args) {
  // implementation of goog.bind()
};

Each parameter and return type is documented with its description and type information in a block comment preceding the declaration of goog.bind(). Java developers will immediately note the ...