Using Google Closure's @typedef tag

问题:

Google's Closure compiler has an "@typedef" tag, but is it OK to use them in your code? (I know it'll work, but is it frowned upon?)

So here's my type

/**
 * The plan object's typedef
 * @typedef {Object}
 */
Types.Plan = {
    "style": "bordersmall",
    "width": "50%",
    "height": "40%",
    "x": "20%",
    "y": "10%",
    "clickable": true,
    "moveable": true
};

And then I can use that type in my JSDoc annotations.

This allows my IDE to give me autocomplete on the passed parameter

So the declared object isn't used anywhere in the code.

/**
 * The Instructions class
 * @param   {Types.Plan}    plan        Plan for position and dimension
 * @param   {Manager}       manager     The manager
 * @param   {Instructions}  parent      This widget's parent's instructions
 * @return  {Instructions}              Returns the new instructions object
 */
Instructions = function(plan, manager, parent){
    plan.
}

So is this ok? Or is there a better solution?

回答1:

@typedef is used to define a type, not to mark an object as a certain type. If you want to mark a certain variable as a certain type, use the @type {<type>} annotation.

@typedef is used to define "short-hand" types for use with @type {...} constructs.

Beware that properties of objects are currently not typed in the Closure Compiler, even if marked, but may be in the future.

回答2:

This is fine. You can also use a record-type to enable additional type checking with the compiler:

/**
 * @typedef {{
 *   style: string, 
 *   width: string, 
 *   height: string, 
 *   x: string, 
 *   y: string, 
 *   clickable: boolean, 
 *   moveable: boolean
 * }} 
 */
var myType = ...

http://code.google.com/closure/compiler/docs/js-for-compiler.html#types

回答3:

A typedef is meant to create a type, so it's frowned upon to also use it as a namespace (assign an object literal to it). I wrote a blog post about various typedef pitfalls a while ago.