我如何 JSDoc 主干属性/选项答案

【问题标题】：How do I JSDoc Backbone Attributes/Options我如何 JSDoc 主干属性/选项
【发布时间】：2014-05-11 12:10:32
【问题描述】：

我正在尝试确定使用 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({
    ...
});

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

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

注意：有几个与此类似的问题（How to jsdoc annotate BackboneJS code?、How do I document AMD + Backbone project with JSDoc3），但它们都专注于让 Backbone 对象得到识别的“大图”。我找不到任何专门解决属性/选项问题的内容。

【问题讨论】：

标签： backbone.js jsdoc3

【解决方案1】：

我最终在这个（非 Backbone 特定的）堆栈溢出线程中找到了答案：How to describe "object" arguments in 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({
    ...
});

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

【讨论】：