如何jsdoc注释BackboneJS代码？

Question

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.

Answer 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

Answer 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;
});