Question

我正在使用YUIdoc。还要别的吗？那么有人能告诉我如何在Ember中正确记录模型，控制器，混合和视图吗？

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

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

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

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

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

Answer 1

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

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

Answer 2

I have found ember-style-guide useful to me. But with few changes:

After the @module statement I write full path to it beginning from the project name. It gives me opportunity to link to it. For example:

/**
 * @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() {
    // ...
  }

});

After the @augments statement I write a full path to module from which the current module is extended. If the module extended from a third part module I write full path of that module (getting it from the import statement). I'm not sure that it's right way, because in the generated doc no links to these modules. I did not found a way to make a link to them. Honestly, I'm not sure that is possible because different projects may use different doc comments engines and there is no way to tie modules (classes) by names.

如何记录Ember App？

2 个答案: