Question

我正在努力弄清楚如何记录大型代码库。我们有一系列组件，其中大多数都有Backbone Models，Views和Collections。 YUIdocs已被选为我们的标准工具。我想确保文档实际上是有用的，并且我不太确定某些可能已经在业界已经确定的标准。

如何记录以下内容？

一个简单的骨干模型：

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

接受设置对象的构造函数，该对象合并到模块的默认值中。似乎在YUIdocs中有一个@default参数，但它似乎不支持一个对象 - 也许我可以在这里采取不同的做法？
```
initialize: function (settings) {
    this.settings = _.extend(this.settings, settings);
}
```

标准骨干参数，例如事件和模型。

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

model: foo

Answer 1

对于简单的主干模型，您需要记录正在返回的对象。在YUIDoc中，它将被称为“类”。它也是可实例化的（你使用“new”关键字），它扩展了一些其他对象。因此，你可以这样开始：

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

默认属性foo，bar和baz，您可以使用@attribute进行记录。在YUI中，属性实际上是一个非常专业的概念，但是当你退一步时，Backbone Model属性在概念上是相似的。所以我认为借用术语是有道理的。否则，您可以使用@property。

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

对于接受设置对象的构造函数，并且该设置对象具有某些默认值，请参阅Y.Router记录的来源：http://yuilibrary.com/yui/docs/api/files/app_js_router.js.html#l38

对于标准的Backbone参数，例如事件和模型，请使用@property。对于事件，您需要用简单的英语描述它设置的事件监听器。

祝你好运，如果您使用IRC，如果您有YUIDoc问题，请随时在freenode.net上的#yui中发出声音！

使用yuidocs记录Backbone代码

1 个答案: