Question

我正在尝试确定使用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对象的“大图”上。我找不到任何专门解决属性/选项问题的方法。

Answer 1

我最终在这个（非特定于主干的）Stack Overflow线程中找到了答案：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标记，那就更好了，所以如果存在，有人将其作为答案发布我很乐意接受这个答案，而不是我自己的答案。

我如何JSDoc Backbone属性/选项

1 个答案: