Documenting Backbone code with yuidocs

Question

I'm struggling with figuring out how to document a large codebase. We have a series of components, most of which have Backbone Models, Views, and Collections. YUIdocs has been chosen as our standard tool. I want to make sure the documentation is actually useful going forward and am not quite certain about some standards that may have already been decided in the industry.

How can I document the following?

• A Simple Backbone Model:

  define(['backbone'], function (Backbone) {
      return Backbone.Model.extend({
          defaults: {
              foo: '',
              bar: '',
              baz: ''
          }
      });
  });
  

• A constructor that accepts a settings object, which is merged into the module's defaults. It seems as though there is a @default paramater in YUIdocs but it doesn't seem to support an object -- perhaps there is something I can do differently here?

  initialize: function (settings) {
      this.settings = _.extend(this.settings, settings);
  }
  

• Standard Backbone parameters such as events and model.

  events: {
      'click #foo' : 'bar'
  }
  
  model: foo
  

Answer 1

For the simple backbone model, you'd document the object that's being returned. In YUIDoc, it would be referred to as a "class". It's also instantiable (you use the "new" keyword with it) and it extends some other object. Therefore, you'd start like this:

/**
 * A customized Backbone.Model that represents...
 * @class MyModel
 * @constructor
 * @extends Backbone.Model
 */
return Backbone.Model.extend({

The default attributes foo, bar, and baz, you could document with @attribute. Attributes are actually a pretty specialized concept in YUI, but when you step back a little, Backbone Model attributes are conceptually similar. So I think it makes sense to borrow the terminology. Otherwise, you could use @property.

/**
 * Indicates that...
 *
 * @attribute rendered
 * @default ''
 * @type String
 */
 foo: ''

For a constructor that accepts a settings object, AND that settings object has certain default values, see the source for how Y.Router is documented: http://yuilibrary.com/yui/docs/api/files/app_js_router.js.html#l38

For standard Backbone parameters such as events and model, use @property. For events, you will want to describe in plain English which event listeners it sets up.

Good luck, and if you use IRC, feel free to chime in #yui on freenode.net if you have YUIDoc questions!