common 下 api 参数优化 review by songym

Author: liqian7

src/common/commontypes/BaseTypes.js

@@ -4,6 +4,7 @@
  */
 
 /**
+ * @function SuperMap.inherit
  * @description 除了 C 和 P 两个必要参数外，可以传递任意数量的对象，这些对象都将继承C。
  * @memberOf SuperMap
  * @param {Object} C - 继承的类。
@@ -26,6 +27,7 @@ SuperMap.inherit = function (C, P) {
 
 
 /**
+ * @function SuperMap.mixin 
  * @description 实现多重继承。
  * @memberOf SuperMap
  * @param {Class|Object} ...mixins - 继承的类。
@@ -78,6 +80,7 @@ SuperMap.mixin = function (...mixins) {
 export var StringExt = SuperMap.String = {
 
     /**
+     * @function SuperMap.String.startsWith
      * @description 判断目标字符串是否以指定的子字符串开头。
      * @param {string} str - 目标字符串。
      * @param {string} sub - 查找的子字符串。
@@ -88,6 +91,7 @@ export var StringExt = SuperMap.String = {
     },
 
     /**
+     * @function SuperMap.String.contains
      * @description 判断目标字符串是否包含指定的子字符串。
      * @param {string} str - 目标字符串。
      * @param {string} sub - 查找的子字符串。
@@ -98,6 +102,7 @@ export var StringExt = SuperMap.String = {
     },
 
     /**
+     * @function SuperMap.String.trim
      * @description 删除一个字符串的开头和结尾处的所有空白字符。
      * @param {string} str - （可能）存在空白字符填塞的字符串。
      * @returns {string} 删除开头和结尾处空白字符后的字符串。
@@ -107,8 +112,9 @@ export var StringExt = SuperMap.String = {
     },
 
     /**
+     * @function SuperMap.String.camelize
      * @description 骆驼式("-")连字符的字符串处理。
-     * 例如: "chicken-head" becomes "chickenHead",
+     * 例如："chicken-head" becomes "chickenHead",
      *       "-chicken-head" becomes "ChickenHead"。
      * @param {string} str - 要处理的字符串，原始内容不应被修改。
      * @returns {string}
@@ -124,9 +130,10 @@ export var StringExt = SuperMap.String = {
     },
 
     /**
+     * @function SuperMap.String.format
      * @description 提供带 ${token} 标记的字符串, 返回 context 对象属性中指定标记的属性值。
      * @example
-     * 示例:
+     * 示例：
      * (code)
      * 1、template = "${value,getValue}";
      *         context = {value: {getValue:function(){return Math.max.apply(null,argument);}}};
@@ -204,18 +211,21 @@ export var StringExt = SuperMap.String = {
     },
 
     /**
-     * @description 寻找带 token 的字符串。
+     * @member {RegExp} [SuperMap.String.tokenRegEx]
+     * @description 寻找带 token 的字符串，默认为 tokenRegEx=/\$\{([\w.]+?)\}/g。
      * @example
      * Examples: ${a}, ${a.b.c}, ${a-b}, ${5}
      */
     tokenRegEx: /\$\{([\w.]+?)\}/g,
 
     /**
-     * @description Used to test strings as numbers.
+     * @member {RegExp} [SuperMap.String.numberRegEx]
+     * @description 判断一个字符串是否只包含一个数值，默认为 numberRegEx=/^([+-]?)(?=\d|\.\d)\d*(\.\d*)?([Ee]([+-]?\d+))?$/。
      */
     numberRegEx: /^([+-]?)(?=\d|\.\d)\d*(\.\d*)?([Ee]([+-]?\d+))?$/,
 
     /**
+     * @function SuperMap.String.isNumeric
      * @description 判断一个字符串是否只包含一个数值。
      * @example
      * (code)
@@ -231,6 +241,7 @@ export var StringExt = SuperMap.String = {
     },
 
     /**
+     * @function SuperMap.String.numericIf
      * @description 把一个看似数值型的字符串转化为一个数值。
      * @returns {(number|string)} 如果能转换为数值则返回数值，否则返回字符串本身。
      */
@@ -249,20 +260,21 @@ export var StringExt = SuperMap.String = {
 export var NumberExt = SuperMap.Number = {
 
     /**
-     *  @description 格式化数字时默认的小数点分隔符。
-     *  @constant
-     *  @default "."
+     * @member {string} [SuperMap.Number.decimalSeparator='.']
+     * @description 格式化数字时默认的小数点分隔符。
+     * @constant
      */
     decimalSeparator: ".",
 
     /**
-     *  @description 格式化数字时默认的千位分隔符。
-     *  @constant
-     *  @default ","
+     * @member {string} [SuperMap.Number.thousandsSeparator=',']
+     * @description 格式化数字时默认的千位分隔符。
+     * @constant
      */
     thousandsSeparator: ",",
 
     /**
+     * @function SuperMap.Number.limitSigDigs
      * @description 限制浮点数的有效数字位数。
      * @param {number} num - 浮点数。
      * @param {integer} sig - 有效位数。
@@ -277,6 +289,7 @@ export var NumberExt = SuperMap.Number = {
     },
 
     /**
+     * @function SuperMap.Number.format
      * @description 数字格式化输出。
      * @param {number} num - 数字。
      * @param {integer} [dec=0]  - 数字的小数部分四舍五入到指定的位数。设置为 null 值时小数部分不变。
@@ -344,6 +357,7 @@ if (!Number.prototype.limitSigDigs) {
  */
 export var FunctionExt = SuperMap.Function = {
     /**
+     * @function SuperMap.Function.bind
      * @description 绑定函数到对象。方便创建 this 的作用域。
      * @param {function} func - 输入函数。
      * @param {Object} object - 对象绑定到输入函数（作为输入函数的 this 对象）。
@@ -363,6 +377,7 @@ export var FunctionExt = SuperMap.Function = {
     },
 
     /**
+     * @function SuperMap.Function.bindAsEventListener
      * @description 绑定函数到对象，在调用该函数时配置并使用事件对象作为第一个参数。
      * @param {function} func - 用于监听事件的函数。
      * @param {Object} object - this 对象的引用。
@@ -375,6 +390,7 @@ export var FunctionExt = SuperMap.Function = {
     },
 
     /**
+     * @function SuperMap.Function.False
      * @description 该函数仅仅返回 false。该函数主要是避免在 IE8 以下浏览中 DOM 事件句柄的匿名函数问题。
      * @example
      * document.onclick = SuperMap.Function.False;
@@ -385,6 +401,7 @@ export var FunctionExt = SuperMap.Function = {
     },
 
     /**
+     * @function SuperMap.Function.True
      * @description 该函数仅仅返回 true。该函数主要是避免在 IE8 以下浏览中 DOM 事件句柄的匿名函数问题。
      * @example
      * document.onclick = SuperMap.Function.True;
@@ -395,6 +412,7 @@ export var FunctionExt = SuperMap.Function = {
     },
 
     /**
+     * @function SuperMap.Function.Void
      * @description 可重用函数，仅仅返回 "undefined"。
      * @returns {undefined}
      */
@@ -412,12 +430,12 @@ export var FunctionExt = SuperMap.Function = {
 export var ArrayExt = SuperMap.Array = {
 
     /**
-     * @description 过滤数组，提供了 ECMA-262 标准中 Array.prototype.filter 函数的扩展。
-     * @see {@link http://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/filter}
+     * @function SuperMap.Array.filter
+     * @description 过滤数组，提供了 ECMA-262 标准中 Array.prototype.filter 函数的扩展。详见：{@link http://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/filter}
      * @param {Array} array - 要过滤的数组。
-     * @param {function} callback - 数组中的每一个元素调用该函数。
-     *     如果函数的返回值为 true，该元素将包含在返回的数组中。该函数有三个参数: 数组中的元素，元素的索引，数组自身。
-     *     如果设置了可选参数 caller，在调用 callback 时，使用可选参数 caller 设置为 callback 的参数。
+     * @param {function} callback - 数组中的每一个元素调用该函数。</br>
+     *     如果函数的返回值为 true，该元素将包含在返回的数组中。该函数有三个参数: 数组中的元素，元素的索引，数组自身。</br>
+     *     如果设置了可选参数 caller，在调用 callback 时，使用可选参数 caller 设置为 callback 的参数。</br>
      * @param {Object} [caller] - 在调用 callback 时，使用参数 caller 设置为 callback 的参数。
      * @returns {Array} callback 函数返回 true 时的元素将作为返回数组中的元素。
      */

src/common/commontypes/Bounds.js

@@ -306,7 +306,7 @@ export class Bounds {
      * @description 在当前 bounds 上扩展 bounds，支持 point，lanlat 和 bounds。扩展后的 bounds 的范围是两者的结合。
      * @example
      * var bounds1 = new SuperMap.Bounds(-50,-50,40,40);
-     * //bounds改变
+     * //bounds 改变
      * bounds.extend(new SuperMap.LonLat(50,60));
      * @param {(SuperMap.Geometry.Point|SuperMap.LonLat|SuperMap.Bounds)} object - 可以是 point、lonlat 和 bounds。
      */
@@ -420,7 +420,7 @@ export class Bounds {
      * @param {float} x - 传入的 x 坐标值。
      * @param {float} y - 传入的 y 坐标值。
      * @param {boolean} [inclusive=true] - 是否包含边界。
-     * @returns {boolean} 传入的 x,y 坐标在当前范围内。
+     * @returns {boolean} 传入的 x，y 坐标是否在当前范围内。
      */
     contains(x, y, inclusive) {
         //set default
@@ -558,7 +558,7 @@ export class Bounds {
 
     /**
      * @function SuperMap.Bounds.prototype.determineQuadrant
-     * @description 判断传入坐标在 bounds 范围内的象限。以 bounds 中心点为坐标原点。
+     * @description 判断传入坐标是否在 bounds 范围内的象限。以 bounds 中心点为坐标原点。
      * @example
      * var bounds = new SuperMap.Bounds(-180,-90,100,80);
      * //str = "tr";
@@ -671,7 +671,7 @@ export class Bounds {
      * @description 通过字符串参数创建新的 bounds 的构造函数。
      * @example
      * var bounds = SuperMap.Bounds.fromString("-180,-90,100,80");
-     * @param {string} str - 边界字符串，用逗号隔开 (e.g. <i>"5,42,10,45"</i>)。
+     * @param {string} str - 边界字符串，用逗号隔开（e.g. <i>"5,42,10,45"</i>）。
      * @param {boolean} [reverseAxisOrder=false] - 是否反转轴顺序。
      * 如果设为true，则倒转顺序（bottom,left,top,right），否则按正常轴顺序（left,bottom,right,top）。
      * @returns {SuperMap.Bounds} 返回给定的字符串创建的新的边界对象。
@@ -686,7 +686,7 @@ export class Bounds {
      * @description 通过边界框数组创建 Bounds。
      * @example
      * var bounds = SuperMap.Bounds.fromArray([-180,-90,100,80]);
-     * @param {Array.<float>} bbox - 边界值数组。(e.g. <i>[5,42,10,45]</i>)。
+     * @param {Array.<float>} bbox - 边界值数组。（e.g. <i>[5,42,10,45]</i>）。
      * @param {boolean} [reverseAxisOrder=false] - 是否是反转轴顺序。如果设为true，则倒转顺序（bottom,left,top,right），否则按正常轴顺序（left,bottom,right,top）。
      * @returns {SuperMap.Bounds} 返回根据传入的数组创建的新的边界对象。
      */

src/common/commontypes/Credential.js

@@ -2,10 +2,10 @@
 
 /**
  * @class SuperMap.Credential
- * @classdesc SuperMap 的安全证书类，其中包括 token 等安全验证信息。 
- * 需要使用用户名和密码在："http://localhost:8090/iserver/services/security/tokens" 下申请 value。
- * 获得形如："2OMwGmcNlrP2ixqv1Mk4BuQMybOGfLOrljruX6VcYMDQKc58Sl9nMHsqQaqeBx44jRvKSjkmpZKK1L596y7skQ.." 的 value。
- * 目前支持的功能包括：地图服务、专题图、量算、查询、公交换乘、空间分析、网络分析，不支持轮询功能。
+ * @classdesc SuperMap 的安全证书类，其中包括 token 等安全验证信息。</br>
+ * 需要使用用户名和密码在："http://localhost:8090/iserver/services/security/tokens" 下申请 value。</br>
+ * 获得形如："2OMwGmcNlrP2ixqv1Mk4BuQMybOGfLOrljruX6VcYMDQKc58Sl9nMHsqQaqeBx44jRvKSjkmpZKK1L596y7skQ.." 的 value。</br>
+ * 目前支持的功能包括：地图服务、专题图、量算、查询、公交换乘、空间分析、网络分析，不支持轮询功能。</br>
  * @param {string} value - 访问受安全限制的服务时用于通过安全认证的验证信息。
  * @param {string} [name='token'] - 验证信息前缀，name=value 部分的 name 部分。
  * @example

src/common/commontypes/Date.js

@@ -21,7 +21,7 @@ export var DateExt = SuperMap.Date = {
             return function (date) {
                 return date.toISOString();
             };
-        } else {// //部分浏览器没有，就得自己组合，组合后的字符串规则不变
+        } else {// 部分浏览器没有，就得自己组合，组合后的字符串规则不变
             function pad(num, len) {
                 var str = num + "";
                 while (str.length < len) {

src/common/commontypes/Events.js

@@ -8,7 +8,7 @@ import {Util} from './Util';
  * @class SuperMap.Events
  * @classdesc 事件类。
  * @param {Object} object - 当前事件对象被添加到的 JS 对象。
- * @param {HTMLElement} element - 响应浏览器事件的 dom 元素。
+ * @param {HTMLElement} element - 响应浏览器事件的 DOM 元素。
  * @param {Array.<string>} eventTypes - 自定义应用事件的数组。
  * @param {boolean} [fallThrough=false] - 是否允许事件处理之后向上传递（冒泡），为 false 的时候阻止事件冒泡。
  * @param {Object} options - 事件对象选项。
@@ -54,7 +54,7 @@ export class Events {
 
         /**
          * @member {HTMLElement} SuperMap.Events.prototype.element
-         * @description 接受浏览器事件的DOM节点。
+         * @description 接受浏览器事件的 DOM 节点。
          */
         this.element = null;
 
@@ -71,16 +71,16 @@ export class Events {
         this.eventHandler = null;
 
         /**
-         * @member {boolean} SuperMap.Events.prototype.fallThrough
-         * @description 是否允许事件处理之后向上传递（冒泡），为false的时候阻止事件冒泡。
+         * @member {boolean} [SuperMap.Events.prototype.fallThrough=false]
+         * @description 是否允许事件处理之后向上传递（冒泡），为 false 的时候阻止事件冒泡。
          */
         this.fallThrough = fallThrough;
 
         /**
          * @member {boolean} [SuperMap.Events.prototype.includeXY=false]
          * @description 判断是否让 xy 属性自动创建到浏览器上的鼠标事件，一般设置为 false，如果设置为 true，鼠标事件将会在事件传递过程中自动产生 xy 属性。
-         *              可根据事件对象的 'evt.object' 属性在相关的事件句柄上调用 getMousePosition 函数。这个选项习惯默认为false的原因在于，当创建一个
-         *              事件对象，其主要目的是管理。在一个div的相对定位的鼠标事件，将其设为 true 也是有意义的。这个选项也可以用来控制是否抵消缓存。如果
+         *              可根据事件对象的 'evt.object' 属性在相关的事件句柄上调用 getMousePosition 函数。这个选项习惯默认为 false 的原因在于，当创建一个
+         *              事件对象，其主要目的是管理。在一个 div 的相对定位的鼠标事件，将其设为 true 也是有意义的。这个选项也可以用来控制是否抵消缓存。如果
          *              设为 false 不抵消，如果设为 true，用 this.clearMouseCache() 清除缓存偏移（边界元素偏移，元素在页面的位置偏移）。
          * @example
          *  function named(evt) {
@@ -93,7 +93,7 @@ export class Events {
          * @member {Object} SuperMap.Events.prototype.extensions
          * @description 事件扩展。Keys 代表事件类型，values 代表事件对象。
          * @example
-         * 以扩展"foostart" 和 "fooend" 事件为例。展示替换css属性为foo的元素的click事件。
+         * 以扩展 "foostart" 和 "fooend" 事件为例。展示替换 css 属性为 foo 的元素的 click 事件。
          *
          *   SuperMap.Events.foostart = SuperMap.Class({
      *       initialize: function(target) {
@@ -195,8 +195,8 @@ export class Events {
 
     /**
      * @function SuperMap.Events.prototype.attachToElement
-     * @description 给dom元素绑定浏览器事件。
-     * @param {HTMLDOMElement} element - 绑定浏览器事件的dom元素。
+     * @description 给 DOM 元素绑定浏览器事件。
+     * @param {HTMLDOMElement} element - 绑定浏览器事件的 DOM 元素。
      */
     attachToElement(element) {
         if (this.element) {
@@ -233,10 +233,10 @@ export class Events {
      * @function SuperMap.Events.prototype.on
      * @description 在一个相同的范围内注册监听器的方法，此方法调用 register 函数。
      * @example
-     * // 注册一个"loadstart"监听事件
+     * // 注册一个 "loadstart" 监听事件
      * events.on({"loadstart": loadStartListener});
      *
-     * // 同样注册一个"loadstart"监听事件
+     * // 同样注册一个 "loadstart" 监听事件
      * events.register("loadstart", undefined, loadStartListener);
      *
      * // 同时为对象注册多个监听事件
@@ -246,7 +246,7 @@ export class Events {
      *     scope: object
      * });
      *
-     * // 同时为对象注册多个监听事件，多次调用register方法
+     * // 同时为对象注册多个监听事件，多次调用 register 方法
      * events.register("loadstart", object, loadStartListener);
      * events.register("loadend", object, loadEndListener);
      *
@@ -315,10 +315,10 @@ export class Events {
      * @function SuperMap.Events.prototype.un
      * @description 在一个相同的范围内取消注册监听器的方法，此方法调用 unregister 函数。
      * @example
-     * // 移除"loadstart" 事件监听
+     * // 移除 "loadstart" 事件监听
      * events.un({"loadstart": loadStartListener});
      *
-     * // 使用unregister方法移除"loadstart" 事件监听
+     * // 使用 "unregister" 方法移除 "loadstart" 事件监听
      * events.unregister("loadstart", undefined, loadStartListener);
      *
      * // 取消对象多个事件监听
@@ -381,7 +381,7 @@ export class Events {
      * @description 触发一个特定的注册事件。
      * @param {string} type - 触发事件类型。
      * @param {Event} evt - 事件对象。
-     * @returns {boolean} 返回监听对象，如果返回是false，则停止监听。
+     * @returns {boolean} 返回监听对象，如果返回是 false，则停止监听。
      */
     triggerEvent(type, evt) {
         var listeners = this.listeners[type];

src/common/commontypes/LonLat.js

@@ -109,10 +109,8 @@ export class LonLat {
     /**
      * @function SuperMap.LonLat.prototype.wrapDateLine
      * @description 通过传入的范围对象对坐标对象转换到该范围内。
-     * 如果经度小于给定范围最小精度，则在原经度基础上加上范围宽度，
-     * 直到精度在范围内为止，如果经度大于给定范围则在原经度基础上减去范围宽度。
-     * 换句话说就是将不在经度范围内的坐标转换到范围以内。
-     *  （只会转换 lon，不会转换 lat，主要用于转移到日界线以内）
+     * 如果经度小于给定范围最小精度，则在原经度基础上加上范围宽度，直到精度在范围内为止，如果经度大于给定范围则在原经度基础上减去范围宽度。
+     * 即指将不在经度范围内的坐标转换到范围以内（只会转换 lon，不会转换 lat，主要用于转移到日界线以内）。
      * @example
      * var lonLat1 = new SuperMap.LonLat(420,50);
      * var lonLat2 = lonLat1.wrapDateLine(
@@ -156,12 +154,12 @@ export class LonLat {
 
     /**
      * @function SuperMap.LonLat.fromString
-     * @description 通过字符串生成一个 <SuperMap.LonLat> 对象
+     * @description 通过字符串生成一个 {@link SuperMap.LonLat} 对象。
      * @example
      * var str = "100,50";
      * var lonLat = SuperMap.LonLat.fromString(str);
      * @param {string} str - 字符串的格式：Lon+","+Lat。如："100,50"。
-     * @returns {SuperMap.LonLat} 返回一个 <SuperMap.LonLat> 对象。
+     * @returns {SuperMap.LonLat} 返回一个 {@link SuperMap.LonLat} 对象。
      */
     static fromString(str) {
         var pair = str.split(",");