update jsdoc

Author: 2betop

.jsdoc.json

@@ -0,0 +1,29 @@
+{
+    "tags": {
+        "allowUnknownTags": true
+    },
+    "source": {
+        "includePattern": ".+\\.js(doc)?$",
+        "excludePattern": "(^|\\/|\\\\)_"
+    },
+    "plugins": ["plugins/markdown"],
+    "templates": {
+        "cleverLinks" : false,
+        "monospaceLinks" : false,
+        "default" : {
+          "outputSourceFiles" : true
+        },
+        "systemName" : "FIS3",
+        "footer" : "",
+        "copyright" : "",
+        "navType" : "vertical",
+        "theme" : "cerulean",
+        "linenums" : true,
+        "collapseSymbols" : false,
+        "inverseNav" : true
+    },
+    "markdown": {
+      "parser": "gfm",
+      "hardwrap": true
+    }
+}

index.js

@@ -1,6 +1,5 @@
 /*
- * fis
- * http://fis.baidu.com
+ * fis 模块入口
  */
 
 'use strict';

jsdoc.json

@@ -1,19 +1,12 @@
-/*
- * fis
- * http://fis.baidu.com/
- */
-
 'use strict';
-
 /**
  * Cache 构造器，在 fis 中主要用于缓存目标文件的编译信息和编译结果。
  *
  * @param {String} path 需要被缓存的文件路径。
  * @param {String} dir 缓存目录。
- *
- * @class
  * @inner
- * @memberOf module:fis.cache
+ * @class
+ * @memberOf fis.cache
  */
 var Cache = Object.derive(function(path, dir) {
   var file = fis.util.realpath(path);
@@ -29,13 +22,15 @@ var Cache = Object.derive(function(path, dir) {
   var hash = fis.util.md5(file, 10);
   this.cacheFile = basename + '-c-' + hash + '.tmp';
   this.cacheInfo = basename + '-o-' + hash + '.json';
-}, {
+},
+
+  /** @lends fis.cache~Cache.prototype */
+  {
 
   /**
    * 保存内容以及信息。
    * @param  {String | Buffer} content 文件内容
    * @param  {Object} info 数据信息。
-   * @memberOf module:fis.cache~Cache.prototype
    */
   save: function(content, info) {
     var infos = {
@@ -52,7 +47,6 @@ var Cache = Object.derive(function(path, dir) {
    * 从缓存目录中读取缓存内容。
    * @param  {Object} [file] 如果传入了此参数，从缓存文件中读取的内容将会赋值到 `file.content` 以及数据信息会被赋值到 `file.info`.
    * @return {Boolean} 返回 true, 如果缓存有效，否则返回 false.
-   * @memberOf module:fis.cache~Cache.prototype
    */
   revert: function(file) {
     fis.log.debug('revert cache');
@@ -90,7 +84,6 @@ var Cache = Object.derive(function(path, dir) {
   /**
    * 添加依赖，依赖将会被用来判断缓存是否有效，依赖中，任何一个文件修改时间发生变化，缓存失效。
    * @param {String} filepath 依赖的文件路径。
-   * @memberOf module:fis.cache~Cache.prototype
    */
   addDeps: function(file) {
     var path = fis.util.realpath(file);
@@ -105,7 +98,6 @@ var Cache = Object.derive(function(path, dir) {
   /**
    * 删除依赖。
    * @param {String} filepath 依赖的文件路径。
-   * @memberOf module:fis.cache~Cache.prototype
    */
   removeDeps: function(file) {
     var path = fis.util.realpath(file);
@@ -117,8 +109,7 @@ var Cache = Object.derive(function(path, dir) {
 
   /**
    * 合并 cache 中的依赖列表。
-   * @param {mixed} cache 此对象中的依赖会被合入到改事例依赖中。
-   * @memberOf module:fis.cache~Cache.prototype
+   * @param {mixed} cache 此对象中的依赖会被合入到该事例依赖中。
    */
   mergeDeps: function(cache) {
     var deps = {};
@@ -134,34 +125,57 @@ var Cache = Object.derive(function(path, dir) {
 });
 
 /**
- * 用来创建 Cache 对象， 更多细节请查看 {@link module:fis.cache~Cache Cache} 说明。
+ * 用来创建 ~Cache 对象， 更多细节请查看 {@link fis.cache~Cache ~Cache} 说明。
  *
- * ```js
+ * @example
+ * // 检查该文件是否启用缓存
  * if (file.useCache) {
+ *
+ *   // 如果启用，则创建 cache 对象
  *   file.cache = fis.cache(file.realpath, CACHE_DIR);
- * }
- * ```
  *
- * @module {Function} fis.cache
- * @see {@link module:fis.cache~Cache Cache 类说明}
+ *   // 保存内容以及信息到缓存中。
+ *   file.cache.save('body', {
+ *     foo: 1
+ *   });
+ * }
+ * @see {@link fis.cache~Cache Cache 类说明}
+ * @param {String} path 需要被缓存的文件路径。
+ * @param {String} dir 缓存目录。
+ * @function
+ * @namespace fis.cache
  */
 var exports = module.exports = Cache.factory();
 
 /**
- * 是否开启缓存。
+ * 是否开启缓存。当设置为 false 后, fis 编译将不会启用缓存。
  * @type {Boolean}
+ * @defaultValue true
+ * @memberOf fis.cache
+ * @name enable
  */
 exports.enable = true;
 
 /**
- * {@link module:fis.cache~Cache Cache} 构造器
+ * 指向 {@link fis.cache~Cache ~Cache 类}。
+ * @see {@link fis.cache~Cache Cache 类说明}
+ * @memberOf fis.cache
+ * @name Cache
  */
 exports.Cache = Cache;
 
 /**
  * 清除缓存目录下面指定的目录。
- * @param  {String} name [description]
- * @return {Undefined}
+ * @example
+ *
+ * // 当命令行中设置了 --clean 属性后，开始之前，先清除之前编译产生的缓存文件。
+ * if (options.clean) {
+ *   fis.cache.clean('compile');
+ * }
+ * @param  {String} name 需要清除的目录名
+ * @memberOf fis.cache
+ * @name clean
+ * @function
  */
 exports.clean = function(name) {
   name = name || '';

lib/cache.js

@@ -1,41 +1,48 @@
-/*
- * fis命令行操作处理
- */
-
 /**
  * 命令行相关的信息和工具类方法暴露在此模块中。
- * @exports fis.cli
+ * @namespace fis.cli
  */
 var cli = module.exports = {};
+
 var path = require('path');
 var _ = require('./util.js');
 var util = require('util');
 var lolcat = require('fis-lolcat');
 
 /**
- * 命令名字
- * @type {String}
+ * 命令行工具名字
+ * @memberOf fis.cli
+ * @name name
+ * @defaultValue fis3
  */
 cli.name = 'fis3';
 
-//colors
+/**
+ * 指向 {@link https://www.npmjs.com/package/colors colors} 模块。
+ * @memberOf fis.cli
+ * @name colors
+ */
 cli.colors = require('colors');
 
 //commander object
 cli.commander = null;
 
 /**
  * package.json 中的信息
- * @type {Object}
+ * @memberOf fis.cli
+ * @name info
  */
 cli.info = fis.util.readJSON(path.dirname(__dirname) + '/package.json');
 
 /**
- * 显示帮组信息，主要用来格式化信息，处理缩进等。fis command 插件，可以用此方法来输出帮助信息。
+ * 显示帮助信息，主要用来格式化信息，处理缩进等。fis command 插件，可以用此方法来输出帮助信息。
  *
  * @param  {String} [cmdName]  命令名称
  * @param  {Object} [options]  配置
  * @param  {Array} [commands] 支持的命令集合
+ * @memberOf fis.cli
+ * @name help
+ * @function
  */
 cli.help = function(cmdName, options, commands) {
   var strs = [
@@ -101,6 +108,24 @@ fis.set('modules.commands', ['init', 'install', 'release', 'server', 'inspect'])
 
 /**
  * 输出 fis 版本信息。
+ *
+ * ```
+ * v3.0.0
+ *
+ * /\\\\\\\\\\\\\\\  /\\\\\\\\\\\     /\\\\\\\\\\\
+ * \/\\\///////////  \/////\\\///    /\\\/////////\\\
+ *  \/\\\                 \/\\\      \//\\\      \///
+ *   \/\\\\\\\\\\\         \/\\\       \////\\\
+ *    \/\\\///////          \/\\\          \////\\\
+ *     \/\\\                 \/\\\             \////\\\
+ *      \/\\\                 \/\\\      /\\\      \//\\\
+ *       \/\\\              /\\\\\\\\\\\ \///\\\\\\\\\\\/
+ *        \///              \///////////    \///////////
+ * ```
+ *
+ * @memberOf fis.cli
+ * @name version
+ * @function
  */
 cli.version = function() {
   var content = ['',
@@ -145,9 +170,12 @@ cli.version = function() {
 };
 
 /**
- * fis由命令行到内核执行的入口
+ * fis命令行执行入口。
  * @param  {Array} argv 由 {@link https://github.com/substack/minimist minimist} 解析得到的 argv, 已经转换成了对象。
  * @param  {Array} env  liftoff env
+ * @name run
+ * @memberOf fis.cli
+ * @function
  */
 cli.run = function(argv, env) {
   // [node, realPath(bin/fis.js)]
@@ -184,9 +212,9 @@ cli.run = function(argv, env) {
   } else {
 
     // tip
-    if (argvRaw[2] === 'release' && !env.modulePath) {
-      //fis.log.warning('Local `fis3` not found, use global version instead.');
-    }
+    // if (argvRaw[2] === 'release' && !env.modulePath) {
+    //   fis.log.warning('Local `fis3` not found, use global version instead.');
+    // }
 
     //fix args
     var p = argvRaw.indexOf('--no-color');