2

我正在尝试确定使用 JSDoc 3 将属性和选项参数记录到Backbone.Model.

理想情况下，我希望能够做到：

/**
  * @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({
    ...
});

@option但是JSDoc 3中没有标签，并且@attribute与 Backbone 属性的含义不同。理论上，我认为可以以某种方式制作像我的伪代码中那样的自定义标签，但我找不到任何现有的插件，关于如何创建自定义标签的文档几乎不存在。

所以，既然我现在似乎坚持使用内置标签，我的问题是：我的伪代码（使用实际的 JSDoc 3 标签）的下一个最好的事情是什么？

注意：有几个与此类似的问题（如何 jsdoc 注释 BackboneJS 代码？，如何使用 JSDoc3 记录 AMD + Backbone 项目），但它们都集中在让 Backbone 对象得到识别的“大图”上。我找不到任何专门解决属性/选项问题的内容。

4

1 回答 1

1

我最终在这个（非 Backbone 特定的）堆栈溢出线程中找到了答案：如何在 jsdoc 中描述“对象”参数？.

总而言之，您可以通过制作初始参数（例如@param attributes），然后制作@param attributes.foo或@param options.bar标记来记录属性/选项。换句话说，我的伪代码可以用以下语法正确地重新完成：

/**
  * @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({
    ...
});

我仍然认为如果有某种允许@attribute/@option标记的 JSDoc3-Backbone 插件会更好，所以如果存在并且有人将其作为答案发布，我会很乐意接受该答案而不是我自己的答案。

于 2014-03-31T23:46:50.207 回答