Как документировать приложение Ember?

Я использую YUIdoc. Что-нибудь еще? Ну может ли кто-нибудь сказать мне, как правильно документировать модель, контроллер, микс и вид в Ember?

Например, я пытаюсь документировать это:

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

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

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

EDIT Теперь я использую YUIdoc вместо jsdoc3

Ответ 1

Вам будет сложно использовать JSDoc для приложений Ember, потому что JSDoc анализирует код, а не только комментарии. Ember использует свой собственный классный синтаксис, поэтому JSDoc не сможет распознать много кода. Я лично использую YUIDoc, что и использует команда Ember. (YUIDoc также позволяет импортировать другую документацию для разрешения внешних ссылок, например DS.Model.) Существуют и другие альтернативы. Эта страница дает некоторое сравнение и дает диаграмму различий, которая показывает, какие инструменты анализируют комментарии, а не исходный код.

Кроме того, я понимаю, что я не отвечаю на ваш конкретный вопрос. Но это должно помочь ответить на вопрос о том, какие альтернативы там, что может полностью исключить ваш вопрос JSDoc.

Ответ 2

Я нашел 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). Я не уверен, что это правильно, потому что в созданном документе нет ссылок на эти модули. Я не нашел способ сделать ссылку на них. Честно говоря, я не уверен, что это возможно, потому что разные проекты могут использовать разные механизмы комментариев doc, и нет способа связать модули (классы) по именам.