doc: translate comments to English

lib/egg.js

@@ -11,17 +11,17 @@ class EggCore extends KoaApplication {
 
   /**
    * @constructor
-   * @param {Object} options - 创建应用配置
-   *  - {String} [process.cwd()] baseDir - app root dir, default is `process.cwd()`
-   *  - {String} [application|agent] type
-   *  - {Object} plugins - 自定义插件配置，一般只用于单元测试
+   * @param {Object} options - options
+   * @param {String} [options.baseDir=process.cwd()] - the directory of application
+   * @param {String} [options.type=application|agent] - wheter it's running in app worker or agent worker
+   * @param {Object} [options.plugins] - custom plugins
+   * @since 1.0.0
    */
   constructor(options) {
     options = options || {};
     options.baseDir = options.baseDir || process.cwd();
     options.type = options.type || 'application';
 
-    // 确保 baseDir 存在，是字符串，并且所在目录存在
     assert(typeof options.baseDir === 'string', 'options.baseDir required, and must be a string');
     assert(fs.existsSync(options.baseDir), `Directory ${options.baseDir} not exists`);
     assert(fs.statSync(options.baseDir).isDirectory(), `Directory ${options.baseDir} is not a directory`);
@@ -30,20 +30,21 @@ class EggCore extends KoaApplication {
     super();
 
     /**
-     * {@link EggCore} 初始化传入的参数
      * @member {Object} EggCore#options
+     * @since 1.0.0
      */
     this._options = options;
 
     /**
-     * console 的替代品，但可由 egg 进行控制
+     * logging for EggCore, avoid using console directly
      * @member {Logger} EggCore#console
+     * @since 1.0.0
      */
     this.console = new EggConsoleLogger();
 
     /**
-     * 获取 app 的 Loader
-     * @member {AppWorkerLoader} EggCore#loader
+     * @member {EggLoader} EggCore#loader
+     * @since 1.0.0
      */
     const Loader = this[Symbol.for('egg#loader')];
     assert(Loader, 'Symbol.for(\'egg#loader\') is required');
@@ -57,12 +58,17 @@ class EggCore extends KoaApplication {
     this._initReady();
   }
 
+  /**
+   * alias to options.type
+   * @member {String}
+   * @since 1.0.0
+   */
   get type() {
     return this._options.type;
   }
 
   /**
-   * 应用所在的代码根目录
+   * alias to options.baseDir
    * @member {String}
    * @since 1.0.0
    */
@@ -71,21 +77,20 @@ class EggCore extends KoaApplication {
   }
 
   /**
-   * 统一的 depd API
    * @member {Function}
    * @see https://npmjs.com/package/depd
    * @since 1.0.0
    */
   get deprecate() {
     if (!this[DEPRECATE]) {
-      // 延迟加载，这样允许单元测试通过 process.env.NO_DEPRECATION = '*' 设置不输出
+      // require depd when get, `process.env.NO_DEPRECATION = '*'` should be use when run test everytime
       this[DEPRECATE] = require('depd')('egg');
     }
     return this[DEPRECATE];
   }
 
   /**
-   * 当前应用名, 读取自 `package.json` 的 name 字段。
+   * name in package.json
    * @member {String}
    * @since 1.0.0
    */
@@ -94,7 +99,7 @@ class EggCore extends KoaApplication {
   }
 
   /**
-   * 获取配置，从 `config/config.${env}.js` 读取
+   * alias to {EggCore#loader}
    * @member {Object}
    * @since 1.0.0
    */
@@ -103,7 +108,7 @@ class EggCore extends KoaApplication {
   }
 
   /**
-   * 获取配置，从 `config/config.${env}.js` 读取
+   * alias to {EggCore#loader}
    * @member {Config}
    * @since 1.0.0
    */
@@ -113,36 +118,38 @@ class EggCore extends KoaApplication {
 
   /**
    * close all listeners
+   * @member {Function}
+   * @since 1.0.0
    */
   close() {
     this.emit('close');
     this.removeAllListeners();
   }
 
   /**
-   * 初始化 ready
+   * @member {Function}
    * @private
    */
   _initReady() {
     /**
-     * 注册 ready 方法，当启动完成后触发此方法
+     * register an callback function that will be invoked when application is ready.
      * @member {Function} EggCore#ready
      * @since 1.0.0
      */
 
     /**
-     * 异步启动接口，查看 https://github.com/koajs/koa-ready
-     * 当所有注册的任务完成后才会触发 app.ready，启动才正式完成
+     * If a client starts asynchronously, you can register `readyCallback`,
+     * then the application will wait for the callback to ready
      *
+     * It will log when the callback is not invoked after 10s
      * @member {Function} EggCore#readyCallback
      * @since 1.0.0
      * @example
      * ```js
-     * const done = app.readyCallback('configclient');
-     * configclient.ready(done);
+     * const done = app.readyCallback('mysql');
+     * mysql.ready(done);
      * ```
      */
-    // 默认 10s 没有 ready 就输出日志提示
     require('ready-callback')({ timeout: 10000 }).mixin(this);
 
     this.on('ready_stat', data => {

lib/loader/egg_loader.js

@@ -15,11 +15,12 @@ class EggLoader {
 
   /**
    * @constructor
-   * @param {Object} options
-   * - {String} baseDir - 应用根目录
-   * - {Object} app - app 实例，如果是 Agent Worker 则传入 agent 实例，可为空
-   * - {Logger} logger - logger 实例，默认是 console
-   * - {Object} plugins - 自定义插件配置，测试用
+   * @param {Object} options - options
+   * @param {String} options.baseDir - the directory of application
+   * @param {Object} options.app - Application instance
+   * @param {Logger} options.logger - logger
+   * @param {Object} [options.plugins] - custom plugins
+   * @since 1.0.0
    */
   constructor(options) {
     this.options = options;
@@ -30,20 +31,22 @@ class EggLoader {
     this.app = this.options.app;
 
     /**
-     * 读取 package.json
      * @member {Object} EggLoader#pkg
+     * @since 1.0.0
      */
     this.pkg = require(path.join(this.options.baseDir, 'package.json'));
 
     /**
      * @member {Array} EggLoader#eggPaths
+     * @since 1.0.0
      * @see EggLoader#getEggPaths
      */
     this.eggPaths = this.getEggPaths();
     debug('Loaded eggPaths %j', this.eggPaths);
 
     /**
      * @member {String} EggLoader#serverEnv
+     * @since 1.0.0
      * @see EggLoader#getServerEnv
      */
     this.serverEnv = this.getServerEnv();
@@ -74,6 +77,7 @@ class EggLoader {
    * unittest  | unit test
    *
    * @return {String} serverEnv
+   * @since 1.0.0
    */
   getServerEnv() {
     let serverEnv;
@@ -104,7 +108,7 @@ class EggLoader {
    * Get appname from pkg.name
    *
    * @return {String} appname
-   * @private
+   * @since 1.0.0
    */
   getAppname() {
     if (this.pkg.name) {
@@ -138,6 +142,7 @@ class EggLoader {
    * ```
    *
    * @return {Array} framework directories
+   * @since 1.0.0
    */
   getEggPaths() {
     const eggPaths = [];
@@ -177,6 +182,7 @@ class EggLoader {
    * ```js
    * app.loader.loadFile(path.join(app.options.baseDir, 'config/router.js'));
    * ```
+   * @since 1.0.0
    */
   loadFile(filepath) {
     if (!fs.existsSync(filepath)) {
@@ -203,6 +209,7 @@ class EggLoader {
    * 3. app
    *
    * @return {Array} loadUnits
+   * @since 1.0.0
    */
   getLoadUnits() {
     if (this.dirs) {
@@ -211,7 +218,6 @@ class EggLoader {
 
     const dirs = this.dirs = [];
 
-    // 插件目录，master 没有 plugin
     if (this.orderPlugins) {
       for (const plugin of this.orderPlugins) {
         dirs.push({
@@ -221,7 +227,7 @@ class EggLoader {
       }
     }
 
-    // egg 框架路径
+    // framework or egg path
     for (const eggPath of this.eggPaths) {
       dirs.push({
         path: eggPath,
@@ -261,7 +267,7 @@ class EggLoader {
 }
 
 /**
- * Mixin loader 方法到 BaseLoader，class 不支持多类继承
+ * Mixin methods to EggLoader
  * // ES6 Multiple Inheritance
  * https://medium.com/@leocavalcante/es6-multiple-inheritance-73a3c66d2b6b
  */

lib/loader/mixin/config.js

@@ -15,6 +15,7 @@ module.exports = {
    * Will merge config.default.js 和 config.${env}.js
    *
    * @method EggLoader#loadConfig
+   * @since 1.0.0
    */
   loadConfig() {
     const target = {};

lib/loader/mixin/controller.js

@@ -5,9 +5,9 @@ const path = require('path');
 module.exports = {
 
   /**
-   * load app/controller
-   *
-   * @param {Object} opt LoaderOptions
+   * Load app/controller
+   * @param {Object} opt - LoaderOptions
+   * @since 1.0.0
    */
   loadController(opt) {
     opt = Object.assign({ lowercaseFirst: true }, opt);

lib/loader/mixin/custom.js

@@ -18,6 +18,7 @@ module.exports = {
    *   doAsync(done);
    * }
    * ```
+   * @since 1.0.0
    */
   loadCustomApp() {
     this.getLoadUnits()

lib/loader/mixin/extend.js

@@ -9,60 +9,54 @@ const utils = require('../../utils');
 module.exports = {
 
   /**
-   * 扩展 Agent.prototype 的属性
-   *
-   * 可加载路径查看 {@link EggLoader#getLoadUnits}
+   * mixin Agent.prototype
    * @method EggLoader#loadAgentExtend
+   * @since 1.0.0
    */
   loadAgentExtend() {
     this.loadExtend('agent', this.app);
   },
 
   /**
-   * 扩展 Application.prototype 的属性
-   *
-   * 可加载路径查看 {@link EggLoader#getLoadUnits}
+   * mixin Application.prototype
    * @method EggLoader#loadApplicationExtend
+   * @since 1.0.0
    */
   loadApplicationExtend() {
     this.loadExtend('application', this.app);
   },
 
   /**
-   * 扩展 Request.prototype 的属性
-   *
-   * 可加载路径查看 {@link EggLoader#getLoadUnits}
+   * mixin Request.prototype
    * @method EggLoader#loadRequestExtend
+   * @since 1.0.0
    */
   loadRequestExtend() {
     this.loadExtend('request', this.app.request);
   },
 
   /**
-   * 扩展 Response.prototype 的属性
-   *
-   * 可加载路径查看 {@link EggLoader#getLoadUnits}
+   * mixin Response.prototype
    * @method EggLoader#loadResponseExtend
+   * @since 1.0.0
    */
   loadResponseExtend() {
     this.loadExtend('response', this.app.response);
   },
 
   /**
-   * 扩展 Context.prototype 的属性
-   *
-   * 可加载路径查看 {@link EggLoader#getLoadUnits}
+   * mixin Context.prototype
    * @method EggLoader#loadContextExtend
+   * @since 1.0.0
    */
   loadContextExtend() {
     this.loadExtend('context', this.app.context);
   },
 
   /**
-   * 扩展 app.Helper.prototype 的属性
-   *
-   * 可加载路径查看 {@link EggLoader#getLoadUnits}
+   * mixin app.Helper.prototype
    * @method EggLoader#loadHelperExtend
+   * @since 1.0.0
    */
   loadHelperExtend() {
     if (this.app && this.app.Helper) {
@@ -71,12 +65,11 @@ module.exports = {
   },
 
   /**
-   * 加载 extend 基类
-   *
+   * Loader app/extend/xx.js to `prototype`,
    * @method loadExtend
-   * @param {String} name - 加载的文件名，如 app/extend/{name}.js
-   * @param {Object} proto - 最终将属性合并到 proto 上
-   * @private
+   * @param {String} name - filename which may be `app/extend/{name}.js`
+   * @param {Object} proto - prototype that mixed
+   * @since 1.0.0
    */
   loadExtend(name, proto) {
     // 获取需要加载的文件