如何記錄Ember App？

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 。）還有其他選擇。 此頁面進行了一些比較，並為您提供了一個差異圖表，顯示哪些工具解析注釋而不是源代碼。

此外，我意識到我沒有回答你的具體問題。 但這應該有助於回答有什么替代方案的問題，這可能完全消除你的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語句獲取它）。 我不確定它是否正確，因為在生成的文檔中沒有指向這些模塊的鏈接。 我沒有找到一種方法來鏈接它們。 老實說，我不確定這是否可能，因為不同的項目可能使用不同的doc注釋引擎，並且沒有辦法按名稱綁定模塊（類）。