How to jsdoc annotate BackboneJS code?

问题:

Has anyone ever documented BackboneJS code with JSDoc?

I'm having problems annotating Backbone constructs such as:

User = Backbone.Model.extend({

    defaults: { a: 1 },

    initialize: function () {
        // ...
    },

    doSomething: function (p) {
        // ...
    }
});

Any advice appreciated. Thanks.

回答1:

I think it works somehow like this, if you're talking about the JSDoc Toolkit:

User = Backbone.Model.extend(
/** @lends User.prototype */
 {
  /**
   * @class User class description
   *
   * @augments Backbone.Model
   * @constructs
   *
   * Text for the initialize method
   */
    initialize: function() {}
})

The important bit is the position of the @lends tag!

It can be a bit tricky, but if this doesn't work try out some of the other examples: http://code.google.com/p/jsdoc-toolkit/wiki/CookBook

回答2:

chris_b's answer helped me a lot, the sample as well as the link. I had to drop the @class annotation, though, or it would generate two entries for the class. Furthermore, I'm adding this answer to show how to annotate static class members (class level constants).

(We use require.js.)

define([
    'jquery', 'lodash', 'backbone'
], function($, _, Backbone) {
    "use strict";

    /**
     * Enumeration of constants that represent the different types of Hedgehogs.
     * @memberof models/Hedgehog
     * @enum {string}
     * @readonly
     */
    var types = { 'type1': 'Type 1', 'type2': 'Type 2' };

    var Hedgehog = Backbone.Model.extend(
    /** @lends models/Hedgehog.prototype */
    {
        /**
         * This is the model for Hedgehogs.
         *
         * @augments external:Backbone.Model
         * @constructs
         */
        initialize: function() {
            // your code
        },

        // some more methods
    }, {
        // static class members
        "types": types
    });
    return Hedgehog;
});