How do I JSDoc Backbone Attributes/Options

Question

I am trying to determine the best way to use JSDoc 3 to document the attributes and options arguments to a Backbone.Model.

Ideally I'd like to be able to do:

/**
  * @class
  * @attribute {string} foo the foo attribute
  * @attribute {integer} bar the bar attribute
  * @option    {bolean} baz the baz option
  * @option    {string} qux the qux option
  */
var MyModel = Backbone.Model.extend({
    ...
});

However there is no @option tag in JSDoc 3, and @attribute doesn't mean the same thing as a Backbone attribute. In theory I think one could somehow make custom tags like the ones in my pseudo-code, but I couldn't find any existing plug-in with these, and the documentation on how to create custom tags is almost non-existent.

So, since I seem stuck with the built-in tags for now, my question is: what's the next best thing to my pseudo-code (using actual JSDoc 3 tags)?

NOTE: There are several similar questions to this one (How to jsdoc annotate BackboneJS code?, How do I document AMD + Backbone project with JSDoc3) but they all focus on the "big picture" of getting Backbone objects recognized at all. I couldn't find any that specifically addressed the issue of attributes/options.

score 1 · Accepted Answer · edited May 23 '17 at 12:06

I eventually found the answer myself in this (non-Backbone-specific) Stack Overflow thread: How to describe "object" arguments in jsdoc?.

To summarize, you can document attributes/options by making an initial parameter (eg. @param attributes), then making a @param attributes.foo or @param options.bar tag. In other words, my pseudo code could be re-done properly with the following syntax:

/**
  * @class
  * @param {Object} attributes
  * @param {string} attributes.foo the foo attribute
  * @param {integer} attributes.bar the bar attribute
  * @param {Object} options
  * @param {boolean} options.baz the baz option
  * @param {string} options.qux the qux option
  */
var MyModel = Backbone.Model.extend({
    ...
});

I still think that it'd be preferable if there was some sort of JSDoc3-Backbone plug-in that allowed @attribute/@option tags, so if one exists and someone posts it as an answer I'll gladly accept that answer instead of my own.

How do I JSDoc Backbone Attributes/Options

1 Answers1