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!');
      });
    }
  }
});

使用YUIDoc，评论风格的EmberJS文档？

2 个答案: