如何记录烬应用程序

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

Answer 1

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

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

Answer 2

我发现ember-style-guide对我很有用。但几乎没有改变:

1. 在@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() {
       // ...
     }
   });
   

2. 在@augments语句之后，我写了一个完整的路径到模块，从当前模块扩展。如果模块从第三部分模块扩展，我编写该模块的完整路径(从import语句中获取)。我不确定这是正确的方式，因为在生成的文档中没有链接到这些模块。我没有找到与他们建立联系的方法。老实说，我不确定这是可能的，因为不同的项目可能使用不同的文档注释引擎，没有办法通过名称绑定模块(类)。