ember.js - 如何记录 Ember 应用程序？

Question

我正在使用 YUIdoc。还要别的吗？谁能告诉我如何在 Ember 中正确记录模型、控制器、mixin 和视图？

例如，我试图记录这一点：

App.newModel = DS.Model.extend({
    someProperty: DS.attr('string')
});

App.myController = Ember.Controller.extend({
    someProperty: ...
});

App.myMixin = Ember.Mixin.create({
    someProperty: ...
});

编辑我现在使用 YUIdoc 而不是 jsdoc3

score 10 · Accepted Answer

您将很难将 JSDoc 用于 Ember 应用程序，因为 JSDoc 解析代码而不仅仅是注释。Ember 使用自己的类类语法，因此 JSDoc 无法识别很多代码。我个人使用YUIDoc，这是 Ember 团队使用的。（YUIDoc 还允许您导入其他文档来解析外部引用，例如DS.Model。）不过还有其他选择。此页面进行了一些比较，并为您提供了一个差异图表，显示哪些工具解析注释而不是源代码。

另外，我意识到我没有回答你的具体问题。但这应该有助于回答有哪些替代方案的问题，这可能会完全消除您的 JSDoc 问题。

score 3 · Accepted Answer

我发现ember-style-guide对我有用。但变化不大：

在@module声明之后，我从项目名称开始写它的完整路径。它让我有机会链接到它。例如：

/**
 * @module dashboard/models/node
 * @augments module:ember-data/system/model
 * @public
 */
export default DS.Model.extend({

  /**
   * @type {module:dashboard/models/node}
   */
  parent: DS.belongsTo("node"),

  /**
   * @type {Array<module:dashboard/models/node>}
   */
  childs: DS.hasMany("node"),

  /**
   * @method
   * @return {module:dashboard/models/node}
   */
  getFirstChild() {
    // ...
  }

});

在@augments语句之后，我写了一个完整路径，指向扩展当前模块的模块。如果模块是从第三方模块扩展而来的，我会编写该模块的完整路径（从import语句中获取）。我不确定这是否正确，因为在生成的文档中没有指向这些模块的链接。我没有找到与他们建立链接的方法。老实说，我不确定这是否可行，因为不同的项目可能使用不同的文档注释引擎，并且无法通过名称来绑定模块（类）。

ember.js - 如何记录 Ember 应用程序？

2 回答 2

Related

Reference