Skip to content

Commit c5126c0

Browse files
xiongjiaojiaoxiongjiaojiao
committed
【update】common 文档描述优化; review by luox
1 parent 7168ad7 commit c5126c0

219 files changed

Lines changed: 534 additions & 873 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎src/common/commontypes/Bounds.js‎

Lines changed: 28 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -11,11 +11,10 @@ import {Util} from './Util';
1111
* @deprecatedclass SuperMap.Bounds
1212
* @category BaseTypes Geometry
1313
* @classdesc 表示边界类实例。使用 bounds 之前需要设置 left，bottom，right，top 四个属性，这些属性的初始值为 null。
14-
* @param {number} [left] - 左边界，注意考虑宽度，理论上小于 right 值。
14+
* @param {number|Array.<number>} [left] - 如果是number，则表示左边界，注意考虑宽度，理论上小于 right 值。如果是数组，则表示 [left, bottom, right, top] 左下右上组成的数组。
1515
* @param {number} [bottom] - 下边界。考虑高度，理论上小于 top 值。
1616
* @param {number} [right] - 右边界。
1717
* @param {number} [top] - 上边界。
18-
* @param {Array.<number>} [array] - [left, bottom, right, top]，如果同时传多个参数，则使用左下右上组成的数组。
1918
* @example
2019
* var bounds = new Bounds();
2120
* bounds.extend(new LonLat(4,5));
@@ -71,7 +70,7 @@ export class Bounds {
7170
* @example
7271
* var bounds1 = new Bounds(-180,-90,180,90);
7372
* var bounds2 = bounds1.clone();
74-
* @returns {Bounds} 返回一个克隆的 bounds。
73+
* @returns {Bounds} 克隆后的 bounds。
7574
*/
7675
clone() {
7776
return new Bounds(this.left, this.bottom,
@@ -164,15 +163,15 @@ export class Bounds {
164163
}
165164
}
166165

167-
/**
168-
* @function Bounds.prototype.toGeometry
169-
* @description 基于当前边界范围创建一个新的多边形对象。
170-
* @example
171-
* var bounds = new Bounds(-180,-90,100,80);
172-
* // Polygon对象
173-
* var geo = bounds.toGeometry();
174-
* @returns {Polygon} 基于当前 bounds 坐标创建的新的多边形。
175-
*/
166+
///**
167+
// * @function Bounds.prototype.toGeometry
168+
// * @description 基于当前边界范围创建一个新的多边形对象。
169+
// * @example
170+
// * var bounds = new Bounds(-180,-90,100,80);
171+
// * // Polygon对象
172+
// * var geo = bounds.toGeometry();
173+
// * @returns {Polygon} 基于当前 bounds 坐标创建的新的多边形。
174+
// */
176175
// toGeometry() {
177176
// return new Polygon([
178177
// new LinearRing([
@@ -204,7 +203,7 @@ export class Bounds {
204203
* var bounds = new Bounds(-180,-90,100,80);
205204
* //height = 170;
206205
* var height = bounds.getHeight();
207-
* @returns {float} 返回边界高度（top 减去 bottom）。
206+
* @returns {float} 边界高度（top 减去 bottom）。
208207
*/
209208
getHeight() {
210209
return (this.top - this.bottom);
@@ -216,7 +215,7 @@ export class Bounds {
216215
* @example
217216
* var bounds = new Bounds(-180,-90,100,80);
218217
* var size = bounds.getSize();
219-
* @returns {Size} 返回边框大小。
218+
* @returns {Size} 边框大小。
220219
*/
221220
getSize() {
222221
return new Size(this.getWidth(), this.getHeight());
@@ -228,7 +227,7 @@ export class Bounds {
228227
* @example
229228
* var bounds = new Bounds(-180,-90,100,80);
230229
* var pixel = bounds.getCenterPixel();
231-
* @returns {Pixel} 返回像素格式的当前范围的中心点。
230+
* @returns {Pixel} 像素格式的当前范围的中心点。
232231
*/
233232
getCenterPixel() {
234233
return new Pixel((this.left + this.right) / 2,
@@ -241,7 +240,7 @@ export class Bounds {
241240
* @example
242241
* var bounds = new Bounds(-180,-90,100,80);
243242
* var lonlat = bounds.getCenterLonLat();
244-
* @returns {LonLat} 返回当前地理范围的中心点。
243+
* @returns {LonLat} 当前地理范围的中心点。
245244
*/
246245
getCenterLonLat() {
247246
if (!this.centerLonLat) {
@@ -260,7 +259,7 @@ export class Bounds {
260259
* var bounds2 = bounds.scale(2);
261260
* @param {float} [ratio=1] - 需要扩大的比例。
262261
* @param {(Pixel|LonLat)} [origin] - 扩大时的基准点，默认为当前 bounds 的中心点。
263-
* @returns {Bounds} 返回通过 ratio、origin 计算得到的新的边界范围。
262+
* @returns {Bounds} 通过 ratio、origin 计算得到的新的边界范围。
264263
*/
265264
scale(ratio, origin) {
266265
ratio = ratio ? ratio : 1;
@@ -294,9 +293,9 @@ export class Bounds {
294293
* var bounds1 = new Bounds(-50,-50,40,40);
295294
* //bounds2 是新的 bounds
296295
* var bounds2 = bounds.add(20,10);
297-
* @param {float} x - 传入坐标点的 x 坐标。
298-
* @param {float} y - 传入坐标点的 y 坐标。
299-
* @returns {Bounds} 返回一个新的 bounds，此 bounds 的坐标是由传入的 x，y 参数与当前 bounds 坐标计算所得。
296+
* @param {float} x - 坐标点的 x 坐标。
297+
* @param {float} y - 坐标点的 y 坐标。
298+
* @returns {Bounds} 新的 bounds，此 bounds 的坐标是由传入的 x，y 参数与当前 bounds 坐标计算所得。
300299
*/
301300
add(x, y) {
302301
if ((x == null) || (y == null)) {
@@ -422,8 +421,8 @@ export class Bounds {
422421
* var bounds = new Bounds(-50,-50,40,40);
423422
* //isContains = true
424423
* var isContains = bounds.contains(40,40,true);
425-
* @param {float} x - 传入的 x 坐标值。
426-
* @param {float} y - 传入的 y 坐标值。
424+
* @param {float} x - x 坐标值。
425+
* @param {float} y - y 坐标值。
427426
* @param {boolean} [inclusive=true] - 是否包含边界。
428427
* @returns {boolean} 传入的 x，y 坐标是否在当前范围内。
429428
*/
@@ -542,8 +541,8 @@ export class Bounds {
542541
* @param {Bounds} bounds - 目标边界。
543542
* @param {boolean} [partial=false] - 目标边界的任意部分都包含在当前边界中则被认为是包含关系。
544543
* 如果设为 false，整个目标边界全部被包含在当前边界范围内。
545-
* @param {boolean} [inclusive=true] - 边缘共享被视为包含。
546-
* @returns {boolean} 传入的边界被当前边界包含。
544+
* @param {boolean} [inclusive=true] - 边缘共享是否被视为包含。
545+
* @returns {boolean} 传入的边界是否被当前边界包含。
547546
*/
548547
containsBounds(bounds, partial, inclusive) {
549548
if (partial == null) {
@@ -640,7 +639,7 @@ export class Bounds {
640639
* @example
641640
* var bounds = new Bounds(-180,-90,100,80);
642641
* var obj = bounds.toServerJSONObject();
643-
* @returns {Object} 返回 JSON 格式的 Object 对象。
642+
* @returns {Object} JSON 格式的 Object 对象。
644643
*/
645644
toServerJSONObject() {
646645
var jsonObject = {
@@ -679,7 +678,7 @@ export class Bounds {
679678
* @param {string} str - 边界字符串，用逗号隔开（e.g. <i>"5,42,10,45"</i>）。
680679
* @param {boolean} [reverseAxisOrder=false] - 是否反转轴顺序。
681680
* 如果设为true，则倒转顺序（bottom,left,top,right），否则按正常轴顺序（left,bottom,right,top）。
682-
* @returns {Bounds} 返回给定的字符串创建的新的边界对象。
681+
* @returns {Bounds} 给定的字符串创建的新的边界对象。
683682
*/
684683
static fromString(str, reverseAxisOrder) {
685684
var bounds = str.split(",");
@@ -693,7 +692,7 @@ export class Bounds {
693692
* var bounds = Bounds.fromArray([-180,-90,100,80]);
694693
* @param {Array.<float>} bbox - 边界值数组。（e.g. <i>[5,42,10,45]</i>）。
695694
* @param {boolean} [reverseAxisOrder=false] - 是否是反转轴顺序。如果设为true，则倒转顺序（bottom,left,top,right），否则按正常轴顺序（left,bottom,right,top）。
696-
* @returns {Bounds} 返回根据传入的数组创建的新的边界对象。
695+
* @returns {Bounds} 根据传入的数组创建的新的边界对象。
697696
*/
698697
static fromArray(bbox, reverseAxisOrder) {
699698
return reverseAxisOrder === true ?
@@ -706,8 +705,8 @@ export class Bounds {
706705
* @description 通过传入的边界大小来创建新的边界。
707706
* @example
708707
* var bounds = Bounds.fromSize(new Size(20,10));
709-
* @param {Size} size - 传入的边界大小。
710-
* @returns {Bounds} 返回根据传入的边界大小的创建新的边界。
708+
* @param {Size} size - 边界大小。
709+
* @returns {Bounds} 根据传入的边界大小的创建新的边界。
711710
*/
712711
static fromSize(size) {
713712
return new Bounds(0,

‎src/common/commontypes/Credential.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ export class Credential {
4141
* var credential = new Credential("valueString","token");
4242
* //这里 str = "token=valueString";
4343
* var str = credential.getUrlParameters();
44-
* @returns {string} 返回安全信息组成的 url 片段。
44+
* @returns {string} 安全信息组成的 url 片段。
4545
*/
4646
getUrlParameters() {
4747
//当需要其他安全信息的时候，则需要return this.name + "=" + this.value + "&" + "...";的形式添加。
@@ -56,7 +56,7 @@ export class Credential {
5656
* var credential = new Credential("2OMwGmcNlrP2ixqv1Mk4BuQMybOGfLOrljruX6VcYMDQKc58Sl9nMHsqQaqeBx44jRvKSjkmpZKK1L596y7skQ..","token");
5757
* //这里 str = "2OMwGmcNlrP2ixqv1Mk4BuQMybOGfLOrljruX6VcYMDQKc58Sl9nMHsqQaqeBx44jRvKSjkmpZKK1L596y7skQ..";
5858
* var str = credential.getValue();
59-
* @returns {string} 返回 value 字符串，在 iServer 服务下该 value 值即为 token 值。
59+
* @returns {string} value 字符串，在 iServer 服务下该 value 值即为 token 值。
6060
*/
6161
getValue() {
6262
return this.value;

‎src/common/commontypes/Date.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ export var DateExt = {
5858
* @description 从一个字符串生成一个日期对象。
5959
* @example
6060
* var date = DateExt.parse("2010-08-07");
61-
* @param {string} str - 代表日期的字符串。（例如： "2010", "2010-08", "2010-08-07", "2010-08-07T16:58:23.123Z","2010-08-07T11:58:23.123-06"）。
61+
* @param {string} str - 日期的字符串。（例如： "2010", "2010-08", "2010-08-07", "2010-08-07T16:58:23.123Z","2010-08-07T11:58:23.123-06"）。
6262
* @returns {Date} 日期对象，如果字符串无法被解析，则返回一个无效的日期。(例如 isNaN(date.getTime()))。
6363
*/
6464
parse: function (str) {

‎src/common/commontypes/Events.js‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -272,7 +272,7 @@ export class Events {
272272
* @function Events.prototype.registerPriority
273273
* @description 相同的注册方法，但是在前面增加新的监听者事件查询而代替到方法的结束。
274274
* @param {string} type - 事件注册者的名字。
275-
* @param {Object} [obj=this.object] - 对象绑定方面的回调。
275+
* @param {Object} [obj=this.object] - 对象绑定的回调。
276276
* @param {function} [func] - 回调函数，如果没有特定的回调，则这个函数不做任何事情。
277277
*/
278278
registerPriority(type, obj, func) {
@@ -315,7 +315,7 @@ export class Events {
315315
* @function Events.prototype.unregister
316316
* @description 取消注册。
317317
* @param {string} type - 事件类型。
318-
* @param {Object} [obj=this.object] - 对象绑定方面的回调。
318+
* @param {Object} [obj=this.object] - 对象绑定的回调。
319319
* @param {function} [func] - 回调函数，如果没有特定的回调，则这个函数不做任何事情。
320320
*/
321321
unregister(type, obj, func) {
@@ -350,7 +350,7 @@ export class Events {
350350
* @description 触发一个特定的注册事件。
351351
* @param {string} type - 触发事件类型。
352352
* @param {Event} evt - 事件对象。
353-
* @returns {boolean} 返回监听对象，如果返回是 false，则停止监听。
353+
* @returns {Event|boolean} 监听对象，如果返回是 false，则停止监听。
354354
*/
355355
triggerEvent(type, evt) {
356356
var listeners = this.listeners[type];

‎src/common/commontypes/Geometry.js‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ export class Geometry {
1919
this.CLASS_NAME = "SuperMap.Geometry";
2020
/**
2121
* @member {string} Geometry.prototype.id
22-
* @description 此几何对象的唯一标示符。
22+
* @description 几何对象的唯一标示符。
2323
*
2424
*/
2525
this.id = Util.createUniqueID(this.CLASS_NAME + "_");
@@ -63,7 +63,7 @@ export class Geometry {
6363

6464
/**
6565
* @function Geometry.prototype.clone
66-
* @description 创建克隆的几何图形。克隆的几何图形不设置非标准的属性。
66+
* @description 克隆几何图形。克隆的几何图形不设置非标准的属性。
6767
* @returns {Geometry} 克隆的几何图形。
6868
*/
6969
clone() {
@@ -73,7 +73,7 @@ export class Geometry {
7373

7474
/**
7575
* @function Geometry.prototype.setBounds
76-
* @description 设置此几何对象的 bounds。
76+
* @description 设置几何对象的 bounds。
7777
* @param {Bounds} bounds - 范围。
7878
*/
7979
setBounds(bounds) {
@@ -116,7 +116,7 @@ export class Geometry {
116116
/**
117117
* @function Geometry.prototype.getBounds
118118
* @description 获得几何图形的边界。如果没有设置边界，可通过计算获得。
119-
* @returns {Bounds} 返回的几何对象的边界。
119+
* @returns {Bounds} 几何对象的边界。
120120
*/
121121
getBounds() {
122122
if (this.bounds == null) {

‎src/common/commontypes/LonLat.js‎

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,8 @@ import {Util} from './Util';
88
* @deprecatedclass SuperMap.LonLat
99
* @category BaseTypes Geometry
1010
* @classdesc 这个类用来表示经度和纬度对。
11-
* @param {number} [lon=0.0] - 地图单位上的 X 轴坐标，如果地图是地理投影，则此值是经度，否则，此值是地图地理位置的 x 坐标。
11+
* @param {number|Array.<float>} [lon=0.0] - 地图单位上的 X 轴坐标或者横纵坐标组成的数组；如果地图是地理投影，则此值是经度，否则，此值是地图地理位置的 x 坐标。
1212
* @param {number} [lat=0.0] - 地图单位上的 Y 轴坐标，如果地图是地理投影，则此值是纬度，否则，此值是地图地理位置的 y 坐标。
13-
* @param {Array.<float>} [location] - 如果要同时设置，则使用传入横纵坐标组成的数组。
1413
* @example
1514
* var lonLat = new LonLat(30,45);
1615
* @usage
@@ -55,7 +54,7 @@ export class LonLat {
5554
* @example
5655
* var lonLat = new LonLat(100,50);
5756
* var str = lonLat.toShortString();
58-
* @returns {string} 返回处理后的经纬度字符串。例如："100,50"
57+
* @returns {string} 处理后的经纬度字符串。例如："100,50"
5958
*/
6059
toShortString() {
6160
return (this.lon + "," + this.lat);
@@ -67,7 +66,7 @@ export class LonLat {
6766
* @example
6867
* var lonLat1 = new LonLat(100,50);
6968
* var lonLat2 = lonLat1.clone();
70-
* @returns {LonLat} 返回相同坐标值的新的坐标对象。
69+
* @returns {LonLat} 相同坐标值的新的坐标对象。
7170
*/
7271
clone() {
7372
return new LonLat(this.lon, this.lat);
@@ -80,9 +79,9 @@ export class LonLat {
8079
* var lonLat1 = new LonLat(100,50);
8180
* //lonLat2 是新的对象
8281
* var lonLat2 = lonLat1.add(100,50);
83-
* @param {float} lon - 传入的经度参数。
84-
* @param {float} lat - 传入的纬度参数。
85-
* @returns {LonLat} 返回一个新的 LonLat 对象，此对象的经纬度是由传入的经纬度与当前的经纬度相加所得。
82+
* @param {float} lon - 经度参数。
83+
* @param {float} lat - 纬度参数。
84+
* @returns {LonLat} 新的 LonLat 对象，此对象的经纬度是由传入的经纬度与当前的经纬度相加所得。
8685
*/
8786
add(lon, lat) {
8887
if ((lon == null) || (lat == null)) {
@@ -165,7 +164,7 @@ export class LonLat {
165164
* var str = "100,50";
166165
* var lonLat = LonLat.fromString(str);
167166
* @param {string} str - 字符串的格式：Lon+","+Lat。如："100,50"。
168-
* @returns {LonLat} 返回一个 {@link LonLat} 对象。
167+
* @returns {LonLat} {@link LonLat} 对象。
169168
*/
170169
static fromString(str) {
171170
var pair = str.split(",");
@@ -174,9 +173,9 @@ export class LonLat {
174173

175174
/**
176175
* @function LonLat.fromArray
177-
* @description 通过数组生成一个 <LonLat> 对象。
176+
* @description 通过数组生成一个 {@link LonLat} 对象。
178177
* @param {Array.<float>} arr - 数组的格式，长度只能为2,：[Lon,Lat]。如：[5,-42]。
179-
* @returns {LonLat} 返回一个 <LonLat> 对象。
178+
* @returns {LonLat} {@link LonLat} 对象。
180179
*/
181180
static fromArray(arr) {
182181
var gotArr = Util.isArray(arr),

‎src/common/commontypes/Pixel.js‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
* @class Pixel
77
* @deprecatedclass SuperMap.Pixel
88
* @category BaseTypes Geometry
9-
* @classdesc 此类用 x,y 坐标描绘屏幕坐标（像素点）。
9+
* @classdesc 用 x,y 坐标描绘屏幕坐标（像素点）。
1010
* @param {number} [x=0.0] - x 坐标。
1111
* @param {number} [y=0.0] - y 坐标。
1212
* @param {Pixel.Mode} [mode=Pixel.Mode.LeftTop] - 坐标模式。
@@ -62,7 +62,7 @@ export class Pixel {
6262
* @example
6363
* var pixcel = new Pixel(100,50);
6464
* var pixcel2 = pixcel.clone();
65-
* @returns {Pixel} 返回一个新的与当前 pixel 对象有相同 x、y 坐标的 pixel 对象。
65+
* @returns {Pixel} 新的与当前 pixel 对象有相同 x、y 坐标的 pixel 对象。
6666
*/
6767
clone() {
6868
return new Pixel(this.x, this.y, this.mode);
@@ -95,7 +95,7 @@ export class Pixel {
9595
* var pixcel2 = new Pixel(110,30);
9696
* var distance = pixcel.distanceTo(pixcel2);
9797
*
98-
* @param {Pixel} px - 用于计算的一个 pixel。
98+
* @param {Pixel} px - 需要计算的 pixel。
9999
* @returns {float} 作为参数传入的像素与当前像素点的距离。
100100
*/
101101
distanceTo(px) {
@@ -112,7 +112,7 @@ export class Pixel {
112112
*
113113
* @param {number} x - 传入的 x 值。
114114
* @param {number} y - 传入的 y 值。
115-
* @returns {Pixel} 返回一个新的 pixel 对象，该 pixel 是由当前的 pixel 与传入的 x，y 相加得到。
115+
* @returns {Pixel} 新的 pixel 对象，该 pixel 是由当前的 pixel 与传入的 x，y 相加得到。
116116
*/
117117
add(x, y) {
118118
if (x == null || y == null) {
@@ -130,8 +130,8 @@ export class Pixel {
130130
* //pixcel3 是新的对象
131131
* var pixcel3 = pixcel.offset(pixcel2);
132132
*
133-
* @param {Pixel} px - 传入的 <Pixel> 对象。
134-
* @returns {Pixel} 返回一个新的 pixel，该 pixel 是由当前的 pixel 对象的 x，y 值与传入的 Pixel 对象的 x，y 值相加得到。
133+
* @param {Pixel} px - 传入的 {@link Pixel} 对象。
134+
* @returns {Pixel} 新的 pixel，该 pixel 是由当前的 pixel 对象的 x，y 值与传入的 Pixel 对象的 x，y 值相加得到。
135135
*/
136136
offset(px) {
137137
var newPx = this.clone();

‎src/common/commontypes/Size.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ export class Size {
3434

3535
/**
3636
* @function Size.prototype.toString
37-
* @description 返回此对象的字符串形式。
37+
* @description 返回字符串形式。
3838
* @example
3939
* var size = new Size(10,5);
4040
* var str = size.toString();
@@ -51,7 +51,7 @@ export class Size {
5151
* @example
5252
* var size = new Size(31,46);
5353
* var size2 = size.clone();
54-
* @returns {Size} 返回一个新的与当前 size 对象有相同宽、高的 Size 对象。
54+
* @returns {Size} 新的与当前 size 对象有相同宽、高的 Size 对象。
5555
*/
5656
clone() {
5757
return new Size(this.w, this.h);

0 commit comments

Comments
 (0)