EmberJS文档使用YUIDoc，注释样式

Question

这里有一个emberJS控制器作为示例。如何正确地注释它以使用YUIDoc生成文档？

import Ember from 'ember';
/**
 * ?
 */
export default Ember.Controller.extend({
  queryParams: ['param1', 'param2'],
  /**
   * ?
   */
  param1: '',
  /**
   * ?
   */
  param2: 10,
  /**
  *
  */
  testFunc1(param) {
  },
  /** 
   *
   */
  actions: {
    /**
     * ?
     */
    testFunc2(id) {
    },
    /**
     *  ?
     */
    testFunc3() {
      /**
       * ?
       */
      function testFunc4() {
      }
    }
  }
});

我有兴趣了解emberJS代码文档的最佳实践，所以最后我可以获得具有完整层次结构的适当doco。如有任何帮助，我们将不胜感激。

Answer 1

我找到了一个这样的答案。如果有人有更好的解决方案，请分享。

import Ember from 'ember';
/**
* The login controller shows the login form and sends authentication data to the session.
*
* @class login
* @namespace Controller
*/
export default Ember.Controller.extend({
  /**
  * The session service.
  *
  * @property session
  * @readOnly
  * @type Service
  */
  session: Ember.inject.service('session'),
  /**
  * The identification, usually an username or e-mailaddress.
  *
  * @property identification
  * @type String
  * @default null
  */
  identification: '',
  /**
  * The password.
  *
  * @property password
  * @type String
  * @default null
  */
  password: '',

  actions: {
    /**
    * The authenticate action sends the identification and password to the session.
    *
    * @event authenticate
    * @return undefined
    */
    authenticate() {
      this.get('session').authenticate('authenticator:jwt', this.getProperties('identification', 'password'));
    }
  }
});

Answer 2

这里有一个我用于组件的例子，这些组件也可以在控制器中使用。

/**
 * @module Components
 */
import Ember from 'ember';
import MyMixin from '../mixins/my-mixin';
const { Component, inject, computed } = Ember;
/**
 * My aweseome component
 *
 * ## Example Ussage:
 * ```handlebars
 * {{awesome-thing
 *     foo="bar"
 *     baz=boundProp
 *     doit=(action "myAction")}}
 * ```
 *
 * @class AwesomeThingComponent
 * @extends Ember.Component
 * @uses Mixins.MyMixin
 */
export default Component.extend(MyMixin, {
  /**
   * @property {Services.MyService} myService
   * @private
   */
  myService: inject.service(),
  /**
   * Set this to "bar".
   * @property {String} foo
   * @default foobar
   * @public
   */
  foo: 'foobar',
  /**
   * Bind this property (Data Down).
   * @property {Boolean} baz
   * @public
   */
  /**
   * Private function
   * @method myFunc
   * @private
   */
  myFunc() {
    // Code
  },
  actions: {
    /**
     * This is my closure action
     * @method actions.doit
     * @param {Object} payload the payload that will be sent to the action
     * @return {Promise} any expectation that the action closure will return
     * a value
     * @required
     * @public
     */
    /**
     * Internal action that will call `doit`.
     * @method actions.myAction
     * @private
     */
    myAction() {
      get(this, 'doit')({payload: 1}).then(() => {
        console.log('yeah!');
      });
    }
  }
});