1

我正在努力弄清楚如何记录大型代码库。我们有一系列组件，其中大部分都有 Backbone 模型、视图和集合。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
4

1 回答 1

4

对于简单的主干模型，您将记录返回的对象。在 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 留言！

于 2013-03-03T16:05:02.027 回答