diff --git a/cocos2d/core/value-types/CCAffineTransform.js b/cocos2d/core/value-types/CCAffineTransform.js
index cd9bf1f429..29facd289a 100644
--- a/cocos2d/core/value-types/CCAffineTransform.js
+++ b/cocos2d/core/value-types/CCAffineTransform.js
@@ -25,9 +25,12 @@
****************************************************************************/
/**
- *
cc.AffineTransform class represent an affine transform matrix. It's composed basically by translation, rotation, scale transformations.
+ * !#en
+ * cc.AffineTransform class represent an affine transform matrix. It's composed basically by translation, rotation, scale transformations.
* Please do not use its constructor directly, use cc.affineTransformMake alias function instead.
- *
+ * !#zh
+ * cc.AffineTransform 类代表一个仿射变换矩阵。它基本上是由平移旋转,缩放转变所组成。
+ * 请不要直接使用它的构造,请使用 cc.affineTransformMake 函数代替。
* @class AffineTransform
* @param {Number} a
* @param {Number} b
@@ -47,7 +50,8 @@ cc.AffineTransform = function (a, b, c, d, tx, ty) {
};
/**
- * Create a cc.AffineTransform object with all contents in the matrix
+ * !#en Create a cc.AffineTransform object with all contents in the matrix.
+ * !#zh 用在矩阵中的所有内容创建一个 cc.AffineTransform 对象。
* @method affineTransformMake
*
* @param {Number} a
@@ -63,7 +67,8 @@ cc.affineTransformMake = function (a, b, c, d, tx, ty) {
};
/**
- * Clone a cc.AffineTransform object from the specified transform
+ * !#en Clone a cc.AffineTransform object from the specified transform.
+ * !#zh 克隆指定的 cc.AffineTransform 对象。
* @method affineTransformClone
*
* @param {AffineTransform} t
@@ -74,7 +79,8 @@ cc.affineTransformClone = function (t) {
};
/**
- * Apply the affine transformation on a point.
+ * !#en Apply the affine transformation on a point.
+ * !#zh 应用 Point 到仿射变换矩阵上。
* @method pointApplyAffineTransform
*
* @param {Vec2|Number} point - or x.
@@ -100,7 +106,8 @@ cc._pointApplyAffineTransform = function (x, y, t) { //it will remove.
};
/**
- * Apply the affine transformation on a size.
+ * !#en Apply the affine transformation on a size.
+ * !#zh 应用 Size 到仿射变换矩阵上。
* @method sizeApplyAffineTransform
*
* @param {Size} size
@@ -112,9 +119,14 @@ cc.sizeApplyAffineTransform = function (size, t) {
};
/**
- * Create a identity transformation matrix:
+ * !#en
+ * Create a identity transformation matrix:
* [ 1, 0, 0,
- * 0, 1, 0 ]
+ * 0, 1, 0 ]
+ * !#zh
+ * 创建一个恒等变换矩阵:
+ * [ 1, 0, 0,
+ * 0, 1, 0 ]
*
* @method affineTransformMakeIdentity
* @return {AffineTransform}
@@ -123,10 +135,11 @@ cc.affineTransformMakeIdentity = function () {
return {a: 1.0, b: 0.0, c: 0.0, d: 1.0, tx: 0.0, ty: 0.0};
};
-/**
- * Create a identity transformation matrix:
+/*
+ * Create a identity transformation matrix:
* [ 1, 0, 0,
- * 0, 1, 0 ]
+ * 0, 1, 0 ]
+ *
*
* @method affineTransformIdentity
* @return {AffineTransform}
@@ -138,7 +151,8 @@ cc.affineTransformIdentity = function () {
};
/**
- * Apply the affine transformation on a rect.
+ * !#en Apply the affine transformation on a rect.
+ * !#zh 应用 Rect 到仿射变换矩阵上。
*
* @method rectApplyAffineTransform
* @param {Rect} rect
@@ -188,7 +202,8 @@ cc._rectApplyAffineTransformIn = function(rect, anAffineTransform){
};
/**
- * Create a new affine transformation with a base transformation matrix and a translation based on it.
+ * !#en Create a new affine transformation with a base transformation matrix and a translation based on it.
+ * !#zh 创建一个基础变换矩阵,并在此基础上平移了新的仿射变换。
*
* @method affineTransformTranslate
* @param {AffineTransform} t - The base affine transform object.
@@ -208,7 +223,8 @@ cc.affineTransformTranslate = function (t, tx, ty) {
};
/**
- * Create a new affine transformation with a base transformation matrix and a scale based on it.
+ * !#en Create a new affine transformation with a base transformation matrix and a scale based on it.
+ * !#zh 创建一个基础变换矩阵,并在此基础上进行了 Scale 仿射变换。
* @method affineTransformScale
* @param {AffineTransform} t - The base affine transform object.
* @param {Number} sx - The scale on x axis.
@@ -220,7 +236,8 @@ cc.affineTransformScale = function (t, sx, sy) {
};
/**
- * Create a new affine transformation with a base transformation matrix and a rotation based on it.
+ * !#en Create a new affine transformation with a base transformation matrix and a rotation based on it.
+ * !#zh 创建一个基础变换矩阵,并在此基础上进行了 Rotation 仿射变换。
* @method affineTransformRotate
* @param {AffineTransform} aTransform - The base affine transform object.
* @param {Number} anAngle - The angle to rotate.
@@ -239,8 +256,12 @@ cc.affineTransformRotate = function (aTransform, anAngle) {
};
/**
+ * !#en
* Concatenate a transform matrix to another and return the result:
* t' = t1 * t2
+ * !#zh 拼接变换矩阵到另一个,并返回结果:
+ * t' = t1 * t2
+ *
* @method affineTransformConcat
* @param {AffineTransform} t1 - The first transform object.
* @param {AffineTransform} t2 - The transform object to concatenate.
@@ -256,9 +277,13 @@ cc.affineTransformConcat = function (t1, t2) {
};
/**
+ * !#en
* Concatenate a transform matrix to another
* The results are reflected in the first matrix.
* t' = t1 * t2
+ * !#zh
+ * 拼接变换矩阵到另一个,将结果反射在第一矩阵。
+ * t' = t1 * t2
* @method affineTransformConcatIn
* @param {AffineTransform} t1 - The first transform object.
* @param {AffineTransform} t2 - The transform object to concatenate.
@@ -276,7 +301,8 @@ cc.affineTransformConcatIn = function (t1, t2) {
};
/**
- * Return true if an affine transform equals to another, false otherwise.
+ * !#en Return true if an affine transform equals to another, false otherwise.
+ * !#zh 如果仿射变换等于另一个返回 true,否则为 false
* @method affineTransformEqualToTransform
* @param {AffineTransform} t1
* @param {AffineTransform} t2
@@ -287,7 +313,8 @@ cc.affineTransformEqualToTransform = function (t1, t2) {
};
/**
- * Get the invert transform of an AffineTransform object.
+ * !#en Get the invert transform of an AffineTransform object.
+ * !#zh 获取反向仿射变换的对象
* @method affineTransformInvert
* @param {AffineTransform} t
* @return {AffineTransform} The inverted transform object.
diff --git a/cocos2d/core/value-types/CCColor.js b/cocos2d/core/value-types/CCColor.js
index 686c7fb6ff..155f9ef666 100644
--- a/cocos2d/core/value-types/CCColor.js
+++ b/cocos2d/core/value-types/CCColor.js
@@ -29,12 +29,20 @@ var JS = require('../platform/js');
var Color = (function () {
/**
+ * !#en
* Representation of RGBA colors.
*
* Each color component is a floating point value with a range from 0 to 255.
*
* You can also use the convenience method {{#crossLink "cc/color:method"}}cc.color{{/crossLink}} to create a new Color.
*
+ * !#zh
+ * RGBA 颜色表示。
+ *
+ * 每个 Color 的取值范围在 0 到 255 之间。
+ *
+ * 您也可以使用便捷的方法 {{#crossLink "cc/color:method"}}cc.color{{/crossLink}} 来创建一个新的 Color。
+ *
* @class Color
* @extends ValueType
*/
@@ -64,66 +72,88 @@ var Color = (function () {
var DefaultColors = {
// color: [r, g, b, a]
/**
+ * !#en TODO
+ * !#zh 白色
* @property WHITE
* @type {Color}
* @static
*/
WHITE: [255, 255, 255, 255],
/**
+ * !#en TODO
+ * !#zh 黑色
* @property BLACK
* @type {Color}
* @static
*/
BLACK: [0, 0, 0, 255],
/**
+ * !#en TODO
+ * !#zh 透明
* @property TRANSPARENT
* @type {Color}
* @static
*/
TRANSPARENT:[0, 0, 0, 0],
/**
+ * !#en TODO
+ * !#zh 灰色
* @property GRAY
* @type {Color}
* @static
*/
GRAY: [127.5, 127.5, 127.5],
/**
+ * !#en TODO
+ * !#zh 红色
* @property RED
* @type {Color}
* @static
*/
RED: [255, 0, 0],
/**
+ * !#en TODO
+ * !#zh 绿色
* @property GREEN
* @type {Color}
* @static
*/
GREEN: [0, 255, 0],
/**
+ * !#en TODO
+ * !#zh 蓝色
* @property BLUE
* @type {Color}
* @static
*/
BLUE: [0, 0, 255],
/**
+ * !#en TODO
+ * !#zh 黄色
* @property YELLOW
* @type {Color}
* @static
*/
YELLOW: [255, 235, 4],
/**
+ * !#en TODO
+ * !#zh 橙色
* @property ORANGE
* @type {Color}
* @static
*/
ORANGE: [255, 127, 0],
/**
+ * !#en TODO
+ * !#zh 青色
* @property CYAN
* @type {Color}
* @static
*/
CYAN: [0, 255, 255],
/**
+ * !#en TODO
+ * !#zh 洋红色(品红色)
* @property MAGENTA
* @type {Color}
* @static
@@ -140,18 +170,31 @@ var Color = (function () {
}
/**
- * Clone a new color from the current color.
+ * !#en Clone a new color from the current color.
+ * !#zh 克隆当前颜色。
* @method clone
* @return {Color} Newly created color.
+ * @example
+ * var color = cc.Color.WHITE;
+ * var newColor = color.clone();
+ * cc.log(newColor);
*/
Color.prototype.clone = function () {
return new Color(this.r, this.g, this.b, this.a);
};
/**
+ * !#en TODO
+ * !#zh 当前颜色与指定颜色是否相等。
* @method equals
* @param {Color} other
* @return {Boolean}
+ * @example
+ * var color1 = cc.Color.WHITE;
+ * var color2 = cc.Color.WHITE;
+ * cc.log(color1.equals(color2)); // return true;
+ * color2 = cc.Color.RED;
+ * cc.log(color2.equals(color1)); // return false;
*/
Color.prototype.equals = function (other) {
return other &&
@@ -162,11 +205,14 @@ var Color = (function () {
};
/**
+ * !#en TODO
+ * !#zh 插值
* @method lerp
* @param {Color} to
* @param {number} ratio - the interpolation coefficient.
* @param {Color} [out] - optional, the receiving vector.
* @return {Color}
+ * @example {@link utils/api/engine/docs/cocos2d/core/value-types/CCColor/lerp.js}
*/
Color.prototype.lerp = function (to, ratio, out) {
out = out || new Color();
@@ -182,8 +228,13 @@ var Color = (function () {
};
/**
+ * !#en TODO
+ * !#zh 输出字符串格式。
* @method toString
* @return {String}
+ * @example
+ * var color = cc.Color.WHITE;
+ * color.toString(); // return "rgba(255, 255, 255, 255)"
*/
Color.prototype.toString = function () {
return "rgba(" +
@@ -195,36 +246,56 @@ var Color = (function () {
};
/**
+ * !#en TODO
+ * !#zh 设置 Color 中的 R 属性。
* @method setR
* @param {Number} red - the new Red component.
* @return {Color} this color.
+ * @example
+ * var color = cc.Color.BLACK;
+ * color.setR(255); // return Color {r: 255, g: 0, b: 0, a: 255}
*/
Color.prototype.setR = function (red) {
this.r = red;
return this;
};
/**
+ * !#en TODO
+ * !#zh 设置 Color 中的 G 属性。
* @method setG
* @param {Number} green - the new Green component.
* @return {Color} this color.
+ * @example
+ * var color = cc.Color.BLACK;
+ * color.setG(255); // return Color {r: 0, g: 255, b: 0, a: 255}
*/
Color.prototype.setG = function (green) {
this.g = green;
return this;
};
/**
+ * !#en TODO
+ * !#zh 设置 Color 中的 B 属性。
* @method setB
* @param {Number} blue - the new Blue component.
* @return {Color} this color.
+ * @example
+ * var color = cc.Color.BLACK;
+ * color.setB(255); // return Color {r: 0, g: 0, b: 255, a: 255}
*/
Color.prototype.setB = function (blue) {
this.b = blue;
return this;
};
/**
+ * !#en TODO
+ * !#zh 设置 Color 中的 A (透明度) 属性。
* @method setA
* @param {Number} alpha - the new Alpha component.
* @return {Color} this color.
+ * @example
+ * var color = cc.Color.BLACK;
+ * color.setA(0); // return Color {r: 0, g: 0, b: 0, a: 0}
*/
Color.prototype.setA = function (alpha) {
this.a = alpha;
@@ -232,9 +303,12 @@ var Color = (function () {
};
/**
+ * !#en TODO
+ * !#zh 转换为 CSS 格式。
* @method toCSS
* @param {String} opt - "rgba", "rgb", "#rgb" or "#rrggbb".
* @return {String}
+ * @example {@link utils/api/engine/docs/cocos2d/core/value-types/CCColor/toCSS.js}
*/
Color.prototype.toCSS = function ( opt ) {
if ( opt === 'rgba' ) {
@@ -258,8 +332,14 @@ var Color = (function () {
};
/**
- * Clamp this color to make all components between 0 to 1.
+ * !#en Clamp this color to make all components between 0 to 1.
+ * !#zh 限制颜色数值,在 0 到 255 之间。
* @method clamp
+ * @example
+ * var color = cc.Color.BLACK;
+ * cc.log(color); // return Color {r: 0, g: 0, b: 0, a: 255};
+ * color.r = 1000; // return Color {r: 1000, g: 0, b: 0, a: 255};
+ * color.clamp(); // return Color {r: 255, g: 0, b: 0, a: 255};
*/
Color.prototype.clamp = function () {
this.r = cc.clampf(this.r, 0, 255);
@@ -269,10 +349,15 @@ var Color = (function () {
};
/**
+ * !#en TODO
+ * !#zh 读取 16 进制。
* @method fromHEX
* @param {String} hexString
* @return {Color}
* @chainable
+ * @example
+ * var color = cc.Color.BLACK;
+ * color.fromHEX("#FFFF33"); // return Color {r: 255, g: 255, b: 51, a: 255};
*/
Color.prototype.fromHEX = function (hexString) {
var hex = parseInt(((hexString.indexOf('#') > -1) ? hexString.substring(1) : hexString), 16);
@@ -283,9 +368,15 @@ var Color = (function () {
};
/**
+ * !#en TODO
+ * !#zh 转换为 16 进制。
* @method toHEX
* @param {String} fmt - "#rgb" or "#rrggbb".
* @return {String}
+ * @example
+ * var color = cc.Color.BLACK;
+ * color.toHEX("#rgb"); // return "000";
+ * color.toHEX("#rrggbb"); // return "000000";
*/
Color.prototype.toHEX = function ( fmt ) {
var hex = [
@@ -312,9 +403,13 @@ var Color = (function () {
};
/**
- * Convert to 24bit rgb value.
+ * !#en Convert to 24bit rgb value.
+ * !#zh 转换为 24bit 的RGB值。
* @method toRGBValue
* @return {Number}
+ * @example
+ * var color = cc.Color.YELLOW;
+ * color.toRGBValue(); // return 16771844;
*/
Color.prototype.toRGBValue = function () {
return (cc.clampf(this.r, 0, 255) << 16) +
@@ -323,12 +418,17 @@ var Color = (function () {
};
/**
+ * !#en TODO
+ * !#zh 读取 HSV(色彩模型)格式。
* @method fromHSV
* @param {Number} h
* @param {Number} s
* @param {Number} v
* @return {Color}
* @chainable
+ * @example
+ * var color = cc.Color.YELLOW;
+ * color.fromHSV(0, 0, 1); // return Color {r: 255, g: 255, b: 255, a: 255};
*/
Color.prototype.fromHSV = function ( h, s, v ) {
var rgb = Color.hsv2rgb( h, s, v );
@@ -339,8 +439,13 @@ var Color = (function () {
};
/**
+ * !#en TODO
+ * !#zh 转换为 HSV(色彩模型)格式。
* @method toHSV
* @return {Object} - {h: number, s: number, v: number}.
+ * @example
+ * var color = cc.Color.YELLOW;
+ * color.toHSV(); // return Object {h: 0.1533864541832669, s: 0.9843137254901961, v: 1};
*/
Color.prototype.toHSV = function () {
return Color.rgb2hsv( this.r, this.g, this.b );
@@ -350,11 +455,15 @@ var Color = (function () {
})();
/**
+ * !#en TODO
+ * !#zh RGB 转换为 HSV。
* @method rgb2hsv
* @param {Number} r - red, must be [0, 255].
* @param {Number} g - red, must be [0, 255].
* @param {Number} b - red, must be [0, 255].
* @return {Object} - {h: number, s: number, v: number}.
+ * @example
+ * cc.Color.rgb2hsv(255, 255, 255); // return Object {h: 0, s: 0, v: 1};
*/
Color.rgb2hsv = function ( r, g, b ) {
r = r / 255;
@@ -379,11 +488,15 @@ Color.rgb2hsv = function ( r, g, b ) {
};
/**
+ * !#en TODO
+ * !#zh HSV 转换为 RGB。
* @method hsv2rgb
* @param {Number} h
* @param {Number} s
* @param {Number} v
* @return {Object} - {r: number, g: number, b: number}}, rgb will be in [0, 255].
+ * @example
+ * cc.Color.hsv2rgb(0, 0, 1); // return Object {r: 255, g: 255, b: 255};
*/
Color.hsv2rgb = function ( h, s, v ) {
var rgb = { r: 0, g: 0, b: 0 };
@@ -456,15 +569,20 @@ cc.Color = Color;
*/
/**
+ * !#en
* The convenience method to create a new {{#crossLink "Color/Color:method"}}cc.Color{{/crossLink}}
* Alpha channel is optional. Default value is 255.
+ *
+ * !#zh
+ * 通过该方法来创建一个新的 {{#crossLink "Color/Color:method"}}cc.Color{{/crossLink}}
+ * Alpha 通道是可选的。默认值是 255。
+ *
* @method color
* @param {Number} [r=0]
* @param {Number} [g=0]
* @param {Number} [b=0]
* @param {Number} [a=255]
* @return {Color}
- *
* @example {@link utils/api/engine/docs/cocos2d/core/value-types/CCColor/color.js}
*/
cc.color = function color (r, g, b, a) {
@@ -482,22 +600,29 @@ cc.color = function color (r, g, b, a) {
// Functional style API, for backward compatibility
/**
- * returns true if both ccColor3B are equal. Otherwise it returns false.
+ * !#en returns true if both ccColor3B are equal. Otherwise it returns false.
+ * !#zh 如果两个 Color 相等返回 true。否则返回 false。
* @method colorEqual
* @param {Color} color1
* @param {Color} color2
* @return {Boolean} true if both ccColor3B are equal. Otherwise it returns false.
+ * @example
+ * cc.log(cc.colorEqual(cc.Color.RED, cc.Color.RED)); // return true;
*/
cc.colorEqual = function (color1, color2) {
return color1.r === color2.r && color1.g === color2.g && color1.b === color2.b;
};
/**
+ * !#en
* convert a string of color for style to Color.
- * e.g. "#ff06ff" to : cc.color(255,6,255)
+ * e.g. "#ff06ff" to : cc.color(255,6,255)。
+ * !#zh 16 进制转换 Color。
* @method hexToColor
* @param {String} hex
* @return {Color}
+ * @example
+ * cc.hexToColor("#FFFF33"); // return Color {r: 255, g: 255, b: 51, a: 255};
*/
cc.hexToColor = function (hex) {
hex = hex.replace(/^#?/, "0x");
@@ -509,11 +634,16 @@ cc.hexToColor = function (hex) {
};
/**
+ * !#en
* convert Color to a string of color for style.
* e.g. cc.color(255,6,255) to : "#ff06ff"
+ * !#zh Color 转换为 16进制。
* @method colorToHex
* @param {Color} color
* @return {String}
+ * @example
+ * var color = new cc.Color(255, 6, 255)
+ * cc.colorToHex(color); // return #ff06ff;
*/
cc.colorToHex = function (color) {
var hR = color.r.toString(16), hG = color.g.toString(16), hB = color.b.toString(16);
diff --git a/cocos2d/core/value-types/CCEnum.js b/cocos2d/core/value-types/CCEnum.js
index 1484d2b2f5..b3f5fda4f5 100644
--- a/cocos2d/core/value-types/CCEnum.js
+++ b/cocos2d/core/value-types/CCEnum.js
@@ -26,33 +26,20 @@
// enum
/**
- * Define an enum type. If a enum item has a value of -1, it will be given an Integer number according to it's order in the list. Otherwise it will use the value specified by user who writes the enum definition.
+ * !#en
+ * Define an enum type.
+ * If a enum item has a value of -1, it will be given an Integer number according to it's order in the list.
+ * Otherwise it will use the value specified by user who writes the enum definition.
+ *
+ * !#zh
+ * 定义一个枚举类型。
+ * 如果枚举项具有值-1,它会根据它的顺序列表给出一个整数。
+ * 否则,它会使用用户指定定义的枚举值。
+ *
* @method Enum
* @param {object} obj - a JavaScript literal object containing enum names and values
* @return {object} the defined enum type
- *
- * @example
- Texture.WrapMode = cc.Enum({
- Repeat: -1,
- Clamp: -1
-});
- // Texture.WrapMode.Repeat == 0
- // Texture.WrapMode.Clamp == 1
- // Texture.WrapMode[0] == "Repeat"
- // Texture.WrapMode[1] == "Clamp"
-
- var FlagType = cc.Enum({
- Flag1: 1,
- Flag2: 2,
- Flag3: 4,
- Flag4: 8,
-});
- var AtlasSizeList = cc.Enum({
- 128: 128,
- 256: 256,
- 512: 512,
- 1024: 1024,
-});
+ * @example {@link utils/api/engine/docs/cocos2d/core/value-types/CCEnum/Enum.js}
*/
cc.Enum = function (obj) {
diff --git a/cocos2d/core/value-types/CCPointExtension.js b/cocos2d/core/value-types/CCPointExtension.js
index c7cdb2a1ee..74ba21de2d 100644
--- a/cocos2d/core/value-types/CCPointExtension.js
+++ b/cocos2d/core/value-types/CCPointExtension.js
@@ -32,189 +32,251 @@
*/
/**
- * smallest such that 1.0+FLT_EPSILON != 1.0
- * @constant
- * @type Number
+ * !#en smallest such that 1.0+FLT_EPSILON != 1.0.
+ * !#zh 它是满足 1.0+FLT_EPSILON != 1.0 的最小的正数。
+ * @property POINT_EPSILON
+ * @type {Number}
+ * @static
*/
var POINT_EPSILON = parseFloat('1.192092896e-07F');
/**
- * Returns opposite of point.
+ * !#en Returns opposite of point.
+ * !#zh 返回相反的指定坐标点。
* @method pNeg
* @param {Vec2} point
* @return {Vec2}
+ * @example
+ * cc.pNeg(cc.v2(10, 10));//-- return Vec2 {x: -10, y: -10};
*/
cc.pNeg = function (point) {
return cc.p(-point.x, -point.y);
};
/**
- * Calculates sum of two points.
+ * !#en Calculates sum of two points.
+ * !#zh 返回指定两个向量之间的总和。
* @method pAdd
* @param {Vec2} v1
* @param {Vec2} v2
* @return {Vec2}
- * @examples {@link utils/api/engine/docs/cocos2d/core/support/pAdd.js}
+ * @example
+ * cc.pAdd(cc.v2(1, 1), cc.v2(2, 2));//-- return Vec2 {x: 3, y: 3};
*/
cc.pAdd = function (v1, v2) {
return cc.p(v1.x + v2.x, v1.y + v2.y);
};
/**
- * Calculates difference of two points.
+ * !#en Calculates difference of two points.
+ * !#zh 返回指定两个向量之间的差值。
* @method pSub
* @param {Vec2} v1
* @param {Vec2} v2
* @return {Vec2}
+ * @example
+ * cc.pSub(cc.v2(20, 20), cc.v2(5, 5)); //-- return Vec2 {x: 15, y: 15};
*/
cc.pSub = function (v1, v2) {
return cc.p(v1.x - v2.x, v1.y - v2.y);
};
/**
- * Returns point multiplied by given factor.
+ * !#en Returns point multiplied by given factor.
+ * !#zh 返回向量的指定倍数。
* @method pMult
* @param {Vec2} point
* @param {Number} floatVar
* @return {Vec2}
+ * @example
+ * cc.pMult(cc.v2(5, 5), 4); // return Vec2 {x: 20, y: 20};
*/
cc.pMult = function (point, floatVar) {
return cc.p(point.x * floatVar, point.y * floatVar);
};
/**
- * Calculates midpoint between two points.
+ * !#en Calculates midpoint between two points.
+ * !#zh 两个向量之间的中心点。
* @method pMidpoint
* @param {Vec2} v1
* @param {Vec2} v2
* @return {Vec2}
+ * @example
+ * cc.pMidpoint(cc.v2(10, 10), cc.v2(5, 5)); // return Vec2 {x: 7.5, y: 7.5};
*/
cc.pMidpoint = function (v1, v2) {
return cc.pMult(cc.pAdd(v1, v2), 0.5);
};
/**
- * Calculates dot product of two points.
+ * !#en Calculates dot product of two points.
+ * !#zh 两个向量之间进行点(积)乘。
* @method pDot
* @param {Vec2} v1
* @param {Vec2} v2
* @return {Number}
+ * @example
+ * cc.pDot(cc.v2(20, 20), cc.v2(5, 5)); // return 200;
*/
cc.pDot = function (v1, v2) {
return v1.x * v2.x + v1.y * v2.y;
};
/**
- * Calculates cross product of two points.
+ * !#en Calculates cross product of two points.
+ * !#zh 两个向量之间进行叉(积)乘。
* @method pCross
* @param {Vec2} v1
* @param {Vec2} v2
* @return {Number}
+ * @example
+ * cc.pCross(cc.v2(20, 20), cc.v2(5, 5)); // return 0;
*/
cc.pCross = function (v1, v2) {
return v1.x * v2.y - v1.y * v2.x;
};
/**
- * Calculates perpendicular of v, rotated 90 degrees counter-clockwise -- cross(v, perp(v)) greater than 0
+ * !#en Calculates perpendicular of v, rotated 90 degrees counter-clockwise -- cross(v, perp(v)) greater than 0.
+ * !#zh 将指定向量逆时针旋转 90 度并返回。
* @method pPerp
* @param {Vec2} point
* @return {Vec2}
+ * @example
+ * cc.pPerp(cc.v2(20, 20)); // return Vec2 {x: -20, y: 20};
*/
cc.pPerp = function (point) {
return cc.p(-point.y, point.x);
};
/**
- * Calculates perpendicular of v, rotated 90 degrees clockwise -- cross(v, rperp(v)) smaller than 0
+ * !#en Calculates perpendicular of v, rotated 90 degrees clockwise -- cross(v, rperp(v)) smaller than 0.
+ * !#zh 将指定向量顺时针旋转 90 度并返回。
* @method pRPerp
* @param {Vec2} point
* @return {Vec2}
+ * @example
+ * cc.pRPerp(cc.v2(20, 20)); // return Vec2 {x: 20, y: -20};
*/
cc.pRPerp = function (point) {
return cc.p(point.y, -point.x);
};
/**
- * Calculates the projection of v1 over v2.
+ * !#en Calculates the projection of v1 over v2.
+ * !#zh 投影,v1 在后 v2 上的投影。
* @method pProject
* @param {Vec2} v1
* @param {Vec2} v2
* @return {Vec2}
+ * @example
+ * var v1 = cc.v2(20, 20);
+ * var v2 = cc.v2(5, 5);
+ * cc.pProject(v1, v2); // return Vec2 {x: 20, y: 20};
*/
cc.pProject = function (v1, v2) {
return cc.pMult(v2, cc.pDot(v1, v2) / cc.pDot(v2, v2));
};
/**
- * Rotates two points.
+ * !#en Rotates two points.
+ * !#zh 旋转指定的 2 个向量。
* @method pRotate
* @param {Vec2} v1
* @param {Vec2} v2
* @return {Vec2}
+ * @example
+ * var v1 = cc.v2(20, 20);
+ * var v2 = cc.v2(5, 5);
+ * cc.pRotate(v1, v2); // return Vec2 {x: 0, y: 200};
*/
cc.pRotate = function (v1, v2) {
return cc.p(v1.x * v2.x - v1.y * v2.y, v1.x * v2.y + v1.y * v2.x);
};
/**
- * Unrotates two points.
+ * !#en Unrotates two points.
+ * !#zh 未旋转指定的 2 个向量。
* @method pUnrotate
* @param {Vec2} v1
* @param {Vec2} v2
* @return {Vec2}
+ * @example
+ * var v1 = cc.v2(20, 20);
+ * var v2 = cc.v2(5, 5);
+ * cc.pUnrotate(v1, v2); // return Vec2 {x: 200, y: 0};
*/
cc.pUnrotate = function (v1, v2) {
return cc.p(v1.x * v2.x + v1.y * v2.y, v1.y * v2.x - v1.x * v2.y);
};
/**
- * Calculates the square length of a cc.Vec2 (not calling sqrt() )
+ * !#en Calculates the square length of a cc.Vec2 (not calling sqrt() ).
+ * !#zh 返回指定向量长度的平方。
* @method pLengthSQ
* @param {Vec2} v
* @return {Number}
+ * @example
+ * cc.pLengthSQ(cc.v2(20, 20)); // return 800;
*/
cc.pLengthSQ = function (v) {
return cc.pDot(v, v);
};
/**
- * Calculates the square distance between two points (not calling sqrt() )
+ * !#en Calculates the square distance between two points (not calling sqrt() ).
+ * !#zh 返回指定 2 个向量之间的距离平方。
* @method pDistanceSQ
* @param {Vec2} point1
* @param {Vec2} point2
* @return {Number}
+ * @example
+ * var point1 = cc.v2(20, 20);
+ * var point2 = cc.v2(5, 5);
+ * cc.pDistanceSQ(point1, point2); // return 450;
*/
cc.pDistanceSQ = function(point1, point2){
return cc.pLengthSQ(cc.pSub(point1,point2));
};
/**
- * Calculates distance between point an origin
+ * !#en Calculates distance between point an origin.
+ * !#zh 返回指定向量的长度.
* @method pLength
* @param {Vec2} v
* @return {Number}
+ * @example
+ * cc.pLength(cc.v2(20, 20)); // return 28.284271247461902;
*/
cc.pLength = function (v) {
return Math.sqrt(cc.pLengthSQ(v));
};
/**
- * Calculates the distance between two points
+ * !#en Calculates the distance between two points.
+ * !#zh 返回指定 2 个向量之间的距离。
* @method pDistance
* @param {Vec2} v1
* @param {Vec2} v2
* @return {Number}
+ * @example
+ * var v1 = cc.v2(20, 20);
+ * var v2 = cc.v2(5, 5);
+ * cc.pDistance(v1, v2); // return 21.213203435596427;
*/
cc.pDistance = function (v1, v2) {
return cc.pLength(cc.pSub(v1, v2));
};
/**
- * Returns point multiplied to a length of 1.
+ * !#en Returns this vector with a magnitude of 1.
+ * !#zh 返回一个长度为 1 的标准化过后的向量。
* @method pNormalize
* @param {Vec2} v
* @return {Vec2}
+ * @example
+ * cc.pNormalize(cc.v2(20, 20)); // return Vec2 {x: 0.7071067811865475, y: 0.7071067811865475};
*/
cc.pNormalize = function (v) {
var n = cc.pLength(v);
@@ -222,32 +284,47 @@ cc.pNormalize = function (v) {
};
/**
- * Converts radians to a normalized vector.
+ * !#en Converts radians to a normalized vector.
+ * !#zh 将弧度转换为一个标准的向量,返回坐标 x = cos(a) , y = sin(a)。
* @method pForAngle
* @param {Number} a
* @return {Vec2}
+ * @example
+ * cc.pForAngle(20); // return Vec2 {x: 0.40808206181339196, y: 0.9129452507276277};
*/
cc.pForAngle = function (a) {
return cc.p(Math.cos(a), Math.sin(a));
};
/**
- * Converts a vector to radians.
+ * !#en Converts a vector to radians.
+ * !#zh 返回指定向量转换后的弧度。
* @method pToAngle
* @param {Vec2} v
* @return {Number}
+ * @example
+ * cc.pToAngle(cc.v2(20, 20)); // return 0.7853981633974483;
*/
cc.pToAngle = function (v) {
return Math.atan2(v.y, v.x);
};
/**
- * Clamp a value between from and to.
+ * !#en Clamp a value between from and to.
+ * !#zh
+ * 返回指定限制区域后的数值。
+ * 数值大于 max_inclusive 则返回 max_inclusive。
+ * 数值小于 min_inclusive 则返回 min_inclusive。
+ * 否则返回自身。
* @method clampf
* @param {Number} value
* @param {Number} min_inclusive
* @param {Number} max_inclusive
* @return {Number}
+ * @example
+ * var v1 = cc.clampf(20, 0, 20); // return 20;
+ * var v2 = cc.clampf(-1, 0, 20); // return 0;
+ * var v3 = cc.clampf(10, 0, 20); // return 10;
*/
cc.clampf = function (value, min_inclusive, max_inclusive) {
if (min_inclusive > max_inclusive) {
@@ -259,73 +336,110 @@ cc.clampf = function (value, min_inclusive, max_inclusive) {
};
/**
- * Clamp a value between 0 and 1.
+ * !#en Clamp a value between 0 and 1.
+ * !#zh 返回一个范围在 0 ~ 1 之间的指定数值。
* @method clamp01
* @param {Number} value
* @return {Number}
+ * @example
+ * var v1 = cc.clampf(20); //-- return 1;
+ * var v2 = cc.clampf(-1); //-- return 0;
+ * var v3 = cc.clampf(0.5); //-- return 0.5;
*/
cc.clamp01 = function (value) {
return value < 0 ? 0 : value < 1 ? value : 1;
};
/**
- * Clamp a point between from and to.
+ * !#en Clamp a point between from and to.
+ * !#zh
+ * 返回指定限制区域后的向量。
+ * 向量大于 max_inclusive 则返回 max_inclusive。
+ * 向量小于 min_inclusive 则返回 min_inclusive。
+ * 否则返回自身。
* @method pClamp
* @param {Vec2} p
- * @param {Number} min_inclusive
- * @param {Number} max_inclusive
+ * @param {Vec2} min_inclusive
+ * @param {Vec2} max_inclusive
* @return {Vec2}
+ * @example
+ * var min_inclusive = cc.v2(0, 0);
+ * var max_inclusive = cc.v2(20, 20);
+ * var v1 = cc.pClamp(cc.v2(20, 20), min_inclusive, max_inclusive); // return Vec2 {x: 20, y: 20};
+ * var v2 = cc.pClamp(cc.v2(0, 0), min_inclusive, max_inclusive); // return Vec2 {x: 0, y: 0};
+ * var v3 = cc.pClamp(cc.v2(10, 10), min_inclusive, max_inclusive); // return Vec2 {x: 10, y: 10};
*/
cc.pClamp = function (p, min_inclusive, max_inclusive) {
return cc.p(cc.clampf(p.x, min_inclusive.x, max_inclusive.x), cc.clampf(p.y, min_inclusive.y, max_inclusive.y));
};
/**
- * Quickly convert cc.Size to a cc.Vec2.
+ * !#en Quickly convert cc.Size to a cc.Vec2.
+ * !#zh 快速转换 cc.size 为 cc.vec2。
* @method pFromSize
* @param {Size} s
* @return {Vec2}
+ * @example
+ * cc.pFromSize(new cc.size(20, 20)); //-- return Vec2 {x: 20, y: 20};
*/
cc.pFromSize = function (s) {
return cc.p(s.width, s.height);
};
/**
+ * !#en
* Run a math operation function on each point component
* Math.abs, Math.fllor, Math.ceil, Math.round.
- *
+ * !#zh 通过运行指定的数学运算函数来计算指定的向量。
* @method pCompOp
* @param {Vec2} p
* @param {Function} opFunc
* @return {Vec2}
- * @example {@link utils/api/engine/docs/cocos2d/core/support/pCompOp.js}
+ * @example
+ * cc.pCompOp(cc.p(-10, -10), Math.abs); // return Vec2 {x: 10, y: 10};
*/
cc.pCompOp = function (p, opFunc) {
return cc.p(opFunc(p.x), opFunc(p.y));
};
/**
- * Linear Interpolation between two points a and b.
- * alpha == 0 ? a
- * alpha == 1 ? b
- * otherwise a value between a..b
- *
+ * !#en
+ * Linear Interpolation between two points a and b.
+ * alpha == 0 ? a
+ * alpha == 1 ? b
+ * otherwise a value between a..b.
+ * !#zh
+ * 两个点 A 和 B 之间的线性插值。
+ * alpha == 0 ? a
+ * alpha == 1 ? b
+ * 否则这个数值在 a ~ b 之间。
* @method pLerp
* @param {Vec2} a
* @param {Vec2} b
* @param {Number} alpha
* @return {Vec2}
+ * @example
+ * cc.pLerp(cc.v2(20, 20), cc.v2(5, 5), 0.5); // return Vec2 {x: 12.5, y: 12.5};
*/
cc.pLerp = function (a, b, alpha) {
return cc.pAdd(cc.pMult(a, 1 - alpha), cc.pMult(b, alpha));
};
/**
+ * !#en TODO
+ * !#zh
+ * 进行向量之间的模糊判断。
+ * 判断 2 个向量是否在指定数值的范围之内,如果在则返回 true,反之则返回 false。
* @method pFuzzyEqual
* @param {Vec2} a
* @param {Vec2} b
* @param {Number} variance
* @return {Boolean} if points have fuzzy equality which means equal with some degree of variance.
+ * @example
+ * var a = cc.v2(20, 20);
+ * var b = cc.v2(5, 5);
+ * var b1 = cc.pFuzzyEqual(a, b, 10); // return false;
+ * var b2 = cc.pFuzzyEqual(a, b, 18); // return true;
*/
cc.pFuzzyEqual = function (a, b, variance) {
if (a.x - variance <= b.x && b.x <= a.x + variance) {
@@ -336,17 +450,22 @@ cc.pFuzzyEqual = function (a, b, variance) {
};
/**
- * Multiplies a nd b components, a.x*b.x, a.y*b.y.
+ * !#en Multiplies a nd b components, a.x*b.x, a.y*b.y.
+ * !#zh 组件 a 和 b 向量之间的相乘, a.x * b.x, a.y * b.y。
* @method pCompMult
* @param {Vec2} a
* @param {Vec2} b
* @return {Vec2}
+ * @example
+ * cc.pCompMult(acc.v2(20, 20), cc.v2(5, 5)); // return Vec2 {x: 100, y: 100};
*/
cc.pCompMult = function (a, b) {
return cc.p(a.x * b.x, a.y * b.y);
};
/**
+ * !#en TODO
+ * !#zh 返回两个向量方向之间带正负号的弧度。
* @method pAngleSigned
* @param {Vec2} a
* @param {Vec2} b
@@ -362,6 +481,8 @@ cc.pAngleSigned = function (a, b) {
};
/**
+ * !#en TODO
+ * !#zh 获取当前向量与指定向量之间的弧度角。
* @method pAngle
* @param {Vec2} a
* @param {Vec2} b
@@ -374,7 +495,8 @@ cc.pAngle = function (a, b) {
};
/**
- * Rotates a point counter clockwise by the angle around a pivot.
+ * !#en Rotates a point counter clockwise by the angle around a pivot.
+ * !#zh 返回指定向量逆时针旋转围绕轴心的角度点。
* @method pRotateByAngle
* @param {Vec2} v - v is the point to rotate
* @param {Vec2} pivot - pivot is the pivot, naturally
@@ -391,13 +513,16 @@ cc.pRotateByAngle = function (v, pivot, angle) {
};
/**
+ * !#en
* A general line-line intersection test
* indicating successful intersection of a line
* note that to truly test intersection for segments we have to make
* sure that s & t lie within [0..1] and for rays, make sure s & t > 0
* the hit point is p3 + t * (p4 - p3);
* the hit point also is p1 + s * (p2 - p1);
- *
+ * !#zh
+ * 返回 A 为起点 B 为终点线段 1 所在直线和 C 为起点 D 为终点线段 2 所在的直线是否相交,
+ * 如果相交返回 true,反之则为 false,参数 retP 是返回交点在线段 1、线段 2 上的比例。
* @method pLineIntersect
* @param {Vec2} A - A is the startpoint for the first line P1 = (p1 - p2).
* @param {Vec2} B - B is the endpoint for the first line P1 = (p1 - p2).
@@ -439,7 +564,8 @@ cc.pLineIntersect = function (A, B, C, D, retP) {
};
/**
- * ccpSegmentIntersect return YES if Segment A-B intersects with segment C-D.
+ * !#en ccpSegmentIntersect return YES if Segment A-B intersects with segment C-D.
+ * !#zh 返回线段 A - B 和线段 C - D 是否相交。
* @method pSegmentIntersect
* @param {Vec2} A
* @param {Vec2} B
@@ -456,7 +582,8 @@ cc.pSegmentIntersect = function (A, B, C, D) {
};
/**
- * ccpIntersectPoint return the intersection point of line A-B, C-D.
+ * !#en ccpIntersectPoint return the intersection point of line A-B, C-D.
+ * !#zh 返回线段 A - B 和线段 C - D 的交点。
* @method pIntersectPoint
* @param {Vec2} A
* @param {Vec2} B
@@ -479,7 +606,8 @@ cc.pIntersectPoint = function (A, B, C, D) {
};
/**
- * check to see if both points are equal.
+ * !#en check to see if both points are equal.
+ * !#zh 检查指定的 2 个向量是否相等。
* @method pSameAs
* @param {Vec2} A - A ccp a
* @param {Vec2} B - B ccp b to be compared
@@ -497,7 +625,8 @@ cc.pSameAs = function (A, B) {
// High Perfomance In Place Operationrs ---------------------------------------
/**
- * sets the position of the point to 0.
+ * !#en sets the position of the point to 0.
+ * !#zh 设置指定向量归 0。
* @method pZeroIn
* @param {Vec2} v
*/
@@ -507,7 +636,8 @@ cc.pZeroIn = function(v) {
};
/**
- * copies the position of one point to another.
+ * !#en copies the position of one point to another.
+ * !#zh v1 向量等于 v2 向量的值。
* @method pIn
* @param {Vec2} v1
* @param {Vec2} v2
@@ -518,7 +648,8 @@ cc.pIn = function(v1, v2) {
};
/**
- * multiplies the point with the given factor (inplace).
+ * !#en multiplies the point with the given factor (inplace).
+ * !#zh 向量乘于指定倍数。
* @method pMultIn
* @param {Vec2} point
* @param {Number} floatVar
@@ -529,7 +660,8 @@ cc.pMultIn = function(point, floatVar) {
};
/**
- * subtracts one point from another (inplace).
+ * !#en subtracts one point from another (inplace).
+ * !#zh v1 向量减等于 v2 向量的值。
* @method pSubIn
* @param {Vec2} v1
* @param {Vec2} v2
@@ -540,7 +672,8 @@ cc.pSubIn = function(v1, v2) {
};
/**
- * adds one point to another (inplace).
+ * !#en adds one point to another (inplace).
+ * !#zh v1 向量加等于 v2 向量的值。
* @method pAddIn
* @param {Vec2} v1
* @param {Vec2} v2
@@ -551,7 +684,8 @@ cc.pAddIn = function(v1, v2) {
};
/**
- * normalizes the point (inplace).
+ * !#en normalizes the point (inplace).
+ * !#zh 规范化 v 向量,设置 v 向量长度为 1。
* @method pNormalizeIn
* @param {Vec2} v
*/
diff --git a/cocos2d/core/value-types/CCRect.js b/cocos2d/core/value-types/CCRect.js
index 5bdba66970..c3b88a34e1 100644
--- a/cocos2d/core/value-types/CCRect.js
+++ b/cocos2d/core/value-types/CCRect.js
@@ -27,14 +27,18 @@ var ValueType = require('./CCValueType');
var JS = require('../platform/js');
/**
- * A 2D rectangle defined by x, y position and width, height.
- *
+ * !#en A 2D rectangle defined by x, y position and width, height.
+ * !#zh 通过 X,Y 位置和宽度,高度定义的 2D 矩形。
* @class Rect
* @extends ValueType
*/
/**
+ * !#en
* Constructor of cc.Rect class.
* see {{#crossLink "cc/rect:method"}} cc.rect {{/crossLink}} for convenience method.
+ * !#zh
+ * CC Rect类构造函数。可以通过 {{#crossLink "cc/rect:method"}} cc.rect {{/crossLink}} 简便方法进行创建。
+ *
* @method Rect
* @param {Number} [x=0]
* @param {Number} [y=0]
@@ -58,12 +62,15 @@ JS.extend(Rect, ValueType);
require('../platform/CCClass').fastDefine('cc.Rect', Rect, ['x', 'y', 'width', 'height']);
/**
- * Creates a rectangle from two coordinate values.
+ * !#en Creates a rectangle from two coordinate values.
+ * !#zh 根据指定 2 个向量创建出一个矩形区域。
* @static
* @method fromMinMax
* @param {Vec2} v1
* @param {Vec2} v2
* @return {Rect}
+ * @example
+ * cc.Rect.fromMinMax(cc.v2(10, 10), cc.v2(20, 20)); // return Rect {x: 10, y: 10, width: 10, height: 10};
*/
Rect.fromMinMax = function (v1, v2) {
var min_x = Math.min(v1.x, v2.x);
@@ -75,12 +82,23 @@ Rect.fromMinMax = function (v1, v2) {
};
/**
- * Checks if rect contains.
+ * !#en Checks if rect contains.
+ * !#zh
+ * 判断 2 个矩形是否有包含。
+ * 返回 1 为 a 包含 b,如果 -1 为 b 包含 a,
+ * 0 这则都不包含。
* @static
* @method contain
* @param a {Rect} Rect a
* @param b {Rect} Rect b
* @return {Number} The contains result, 1 is a contains b, -1 is b contains a, 0 is no contains.
+ * @example
+ * var a = new cc.rect(0, 0, 10, 10);
+ * var b = new cc.rect(5, 5, 5, 5);
+ * var c = new cc.rect(20, 20, 10, 10);
+ * cc.Rect.contain(a, b); // return 1;
+ * cc.Rect.contain(b, a); // return -1;
+ * cc.Rect.contain(a, c); // return 0;
*/
Rect.contain = function _Contain (a, b) {
if (a.x <= b.x &&
@@ -103,17 +121,28 @@ Rect.contain = function _Contain (a, b) {
var proto = Rect.prototype;
/**
+ * !#en TODO
+ * !#zh 克隆一个新的 Rect。
* @method clone
* @return {Rect}
+ * @example
+ * var a = new cc.rect(0, 0, 10, 10);
+ * a.clone();// return Rect {x: 0, y: 0, width: 10, height: 10}
*/
proto.clone = function () {
return new Rect(this.x, this.y, this.width, this.height);
};
/**
+ * !#en TODO
+ * !#zh 是否等于指定的矩形。
* @method equals
* @param {Rect} other
* @return {Boolean}
+ * @example
+ * var a = new cc.rect(0, 0, 10, 10);
+ * var b = new cc.rect(0, 0, 10, 10);
+ * a.equals(b);// return true;
*/
proto.equals = function (other) {
return other &&
@@ -124,11 +153,22 @@ proto.equals = function (other) {
};
/**
+ * !#en TODO
+ * !#zh Rect 的线性插值。
* @method lerp
* @param {Rect} to
* @param {Number} ratio - the interpolation coefficient.
* @param {Rect} [out] - optional, the receiving vector.
* @return {Rect}
+ * @example
+ * var a = new cc.rect(0, 0, 10, 10);
+ * var b = new cc.rect(50, 50, 100, 100);
+ * update (dt) {
+ * // method 1;
+ * var c = a.lerp(b, dt * 0.1);
+ * // method 2;
+ * a.lerp(b, dt * 0.1, c);
+ * }
*/
proto.lerp = function (to, ratio, out) {
out = out || new Rect();
@@ -144,8 +184,13 @@ proto.lerp = function (to, ratio, out) {
};
/**
+ * !#en TODO
+ * !#zh Rect 用字符串表示。
* @method toString
* @return {String}
+ * @example
+ * var a = new cc.rect(0, 0, 10, 10);
+ * a.toString();// return "(0.00, 0.00, 10.00, 10.00)";
*/
proto.toString = function () {
return '(' + this.x.toFixed(2) + ', ' + this.y.toFixed(2) + ', ' + this.width.toFixed(2) +
@@ -153,6 +198,8 @@ proto.toString = function () {
};
/**
+ * !#en TODO
+ * !#zh 矩形的左坐标。
* @property xMin
* @type {Number}
*/
@@ -165,6 +212,8 @@ Object.defineProperty(proto, 'xMin', {
});
/**
+ * !#en TODO
+ * !#zh 矩形的顶坐标。
* @property yMin
* @type {Number}
*/
@@ -177,6 +226,8 @@ Object.defineProperty(proto, 'yMin', {
});
/**
+ * !#en TODO
+ * !#zh 矩形的右坐标。
* @property xMax
* @type {Number}
*/
@@ -186,6 +237,8 @@ Object.defineProperty(proto, 'xMax', {
});
/**
+ * !#en TODO
+ * !#zh 矩形的底坐标。
* @property yMax
* @type {Number}
*/
@@ -195,6 +248,8 @@ Object.defineProperty(proto, 'yMax', {
});
/**
+ * !#en TODO
+ * !#zh 矩形的中心点。
* @property center
* @type {Number}
*/
@@ -210,6 +265,8 @@ Object.defineProperty(proto, 'center', {
});
/**
+ * !#en TODO
+ * !#zh 矩形的大小。
* @property {Size} size
*/
Object.defineProperty(proto, 'size', {
@@ -223,38 +280,55 @@ Object.defineProperty(proto, 'size', {
});
/**
+ * !#en TODO
+ * !#zh 当前矩形与指定矩形是否相交。
* @method intersects
* @param {Rect} rect
* @type {Boolean}
+ * @example
+ * var a = new cc.rect(0, 0, 10, 10);
+ * var b = new cc.rect(0, 0, 20, 20);
+ * a.intersects(b);// return true
*/
proto.intersects = function (rect) {
return cc.rectIntersectsRect(this, rect);
};
/**
+ * !#en TODO
+ * !#zh 当前矩形是否包含指定坐标点。
* Returns true if the point inside this rectangle.
* @method contains
* @param {Vec2} point
* @type {Boolean}
+ * @example
+ * var a = new cc.rect(0, 0, 10, 10);
+ * var b = new cc.v2(0, 5);
+ * a.contains(b);// return true
*/
proto.contains = function (point) {
- return (this.x <= point.x &&
- this.x + this.width >= point.x &&
- this.y <= point.y &&
- this.y + this.height >= point.y);
+ return (this.x < point.x &&
+ this.x + this.width > point.x &&
+ this.y < point.y &&
+ this.y + this.height > point.y);
};
/**
- * Returns true if the other rect totally inside this rectangle.
+ * !#en Returns true if the other rect totally inside this rectangle.
+ * !#zh 当前矩形是否包含指定矩形。
* @method containsRect
* @param {Rect} rect
* @type {Boolean}
+ * @example
+ * var a = new cc.rect(0, 0, 10, 10);
+ * var b = new cc.rect(0, 0, 20, 20);
+ * a.containsRect(b);// return true
*/
proto.containsRect = function (rect) {
- return (this.x <= rect.x &&
- this.x + this.width >= rect.x + rect.width &&
- this.y <= rect.y &&
- this.y + this.height >= rect.y + rect.height);
+ return (this.x < rect.x &&
+ this.x + this.width > rect.x + rect.width &&
+ this.y < rect.y &&
+ this.y + this.height > rect.y + rect.height);
};
cc.Rect = Rect;
@@ -264,14 +338,19 @@ cc.Rect = Rect;
*/
/**
+ * !#en
* The convenience method to create a new Rect.
* see {{#crossLink "Rect/Rect:method"}}cc.Rect{{/crossLink}}
+ * !#zh
+ * 该方法用来快速创建一个新的矩形。{{#crossLink "Rect/Rect:method"}}cc.Rect{{/crossLink}}
* @method rect
* @param {Number[]|Number} [x=0]
* @param {Number} [y=0]
* @param {Number} [w=0]
* @param {Number} [h=0]
* @return {Rect}
+ * @example
+ * var a = new cc.rect(0 , 0, 10, 0);
*/
cc.rect = function rect (x, y, w, h) {
return new Rect(x, y, w, h);
@@ -281,11 +360,18 @@ cc.rect = function rect (x, y, w, h) {
// Functional style API, for backward compatibility
/**
- * Check whether a rect's value equals to another.
+ * !#en Check whether a rect's value equals to another.
+ * !#zh 检查一个矩形的值是否等于另一个。
* @method rectEqualToRect
* @param {Rect} rect1
* @param {Rect} rect2
* @return {Boolean}
+ * @example
+ * var a = new cc.rect(0, 0, 10, 10);
+ * var b = new cc.rect(0, 0, 5, 5);
+ * cc.rectEqualToRect(a, b); // return false;
+ * var c = new cc.rect(0, 0, 5, 5);
+ * cc.rectEqualToRect(b, c); // return true;
*/
cc.rectEqualToRect = function (rect1, rect2) {
return rect1 && rect2 && (rect1.x === rect2.x) && (rect1.y === rect2.y) && (rect1.width === rect2.width) && (rect1.height === rect2.height);
@@ -296,11 +382,18 @@ cc._rectEqualToZero = function(rect){
};
/**
- * Check whether the rect1 contains rect2.
+ * !#en Check whether the rect1 contains rect2.
+ * !#zh
+ * 检查 rect1 矩形是否包含 rect2 矩形。
+ * 注意:如果要允许 rect1 和 rect2 的边界重合,应该用 cc.rectOverlapsRect
* @method rectContainsRect
* @param {Rect} rect1
* @param {Rect} rect2
* @return {Boolean}
+ * @example
+ * var a = new cc.rect(0, 0, 20, 20);
+ * var b = new cc.rect(10, 10, 20, 20);
+ * cc.rectContainsRect(a, b); // return true;
*/
cc.rectContainsRect = function (rect1, rect2) {
if (!rect1 || !rect2)
@@ -311,70 +404,99 @@ cc.rectContainsRect = function (rect1, rect2) {
};
/**
- * Returns the rightmost x-value of a rect.
+ * !#en Returns the rightmost x-value of a rect.
+ * !#zh 返回指定矩形的最右边的 x 值。
* @method rectGetMaxX
* @param {Rect} rect
* @return {Number} The rightmost x value.
+ * @example
+ * var a = new cc.rect(10, 0, 20, 20);
+ * cc.rectGetMaxX(a); // return 30;
*/
cc.rectGetMaxX = function (rect) {
return (rect.x + rect.width);
};
/**
- * Return the midpoint x-value of a rect.
+ * !#en Return the midpoint x-value of a rect.
+ * !#zh 返回指定矩形的中心点的 x 值。
* @method rectGetMidX
* @param {Rect} rect
* @return {Number} The midpoint x value.
+ * @example
+ * var a = new cc.rect(10, 0, 20, 20);
+ * cc.rectGetMidX(a); // return 20;
*/
cc.rectGetMidX = function (rect) {
return (rect.x + rect.width / 2.0);
};
/**
- * Returns the leftmost x-value of a rect.
+ * !#en Returns the leftmost x-value of a rect.
+ * !#zh 返回指定矩形的最左边的 x 值。
* @method rectGetMinX
* @param {Rect} rect
* @return {Number} The leftmost x value.
+ * @example
+ * var a = new cc.rect(10, 0, 20, 20);
+ * cc.rectGetMinX(a); // return 10;
*/
cc.rectGetMinX = function (rect) {
return rect.x;
};
/**
- * Return the topmost y-value of a rect.
+ * !#en Return the topmost y-value of a rect.
+ * !#zh 返回一个矩形的最上面的 y 值。
* @method rectGetMaxY
* @param {Rect} rect
* @return {Number} The topmost y value.
+ * @example
+ * var a = new cc.rect(0, 10, 20, 20);
+ * cc.rectGetMaxY(a); // return 30;
*/
cc.rectGetMaxY = function (rect) {
return(rect.y + rect.height);
};
/**
- * Return the midpoint y-value of `rect'.
+ * !#en Return the midpoint y-value of `rect'.
+ * !#zh 返回指定矩形的中心点的 y 值。
* @method rectGetMidY
* @param {Rect} rect
* @return {Number} The midpoint y value.
+ * @example
+ * var a = new cc.rect(0, 10, 20, 20);
+ * cc.rectGetMidY(a); // return 20;
*/
cc.rectGetMidY = function (rect) {
return rect.y + rect.height / 2.0;
};
/**
- * Return the bottommost y-value of a rect.
+ * !#en Return the bottommost y-value of a rect.
+ * !#zh 返回一个矩形的最下面的 y 值。
* @method rectGetMinY
* @param {Rect} rect
* @return {Number} The bottommost y value.
+ * @example
+ * var a = new cc.rect(0, 10, 20, 20);
+ * cc.rectGetMinY(a); // return 10;
*/
cc.rectGetMinY = function (rect) {
return rect.y;
};
/**
- * Check whether a rect contains a point.
+ * !#en Check whether a rect contains a point.
+ * !#zh 检查一个矩形是否包含某个坐标点。
* @method rectContainsPoint
* @param {Rect} rect
* @param {Vec2} point
* @return {Boolean}
+ * @example
+ * var a = new cc.rect(0, 10, 20, 20);
+ * var b = cc.v2(0, 10, 10, 10);
+ * cc.rectContainsPoint(a, b); // return true;
*/
cc.rectContainsPoint = function (rect, point) {
return (point.x >= cc.rectGetMinX(rect) && point.x <= cc.rectGetMaxX(rect) &&
@@ -382,11 +504,16 @@ cc.rectContainsPoint = function (rect, point) {
};
/**
- * Check whether a rect intersect with another.
+ * !#en Check whether a rect intersect with another.
+ * !#zh 检查一个矩形是否与另一个相交。
* @method rectIntersectsRect
* @param {Rect} rectA
* @param {Rect} rectB
* @return {Boolean}
+ * @example
+ * var a = new cc.rect(0, 10, 20, 20);
+ * var b = new cc.rect(0, 10, 10, 10);
+ * cc.rectIntersectsRect(a, b); // return true;
*/
cc.rectIntersectsRect = function (ra, rb) {
var maxax = ra.x + ra.width,
@@ -397,11 +524,16 @@ cc.rectIntersectsRect = function (ra, rb) {
};
/**
- * Check whether a rect overlaps another.
+ * !#en Check whether a rect overlaps another.
+ * !#zh 检查一个矩形是否重叠另一个。
* @method rectOverlapsRect
* @param {Rect} rectA
* @param {Rect} rectB
* @return {Boolean}
+ * @example
+ * var a = new cc.rect(0, 10, 20, 20);
+ * var b = new cc.rect(0, 10, 10, 10);
+ * cc.rectOverlapsRect(a, b); // return true;
*/
cc.rectOverlapsRect = function (rectA, rectB) {
return !((rectA.x + rectA.width < rectB.x) ||
@@ -411,11 +543,16 @@ cc.rectOverlapsRect = function (rectA, rectB) {
};
/**
- * Returns the smallest rectangle that contains the two source rectangles.
+ * !#en Returns the smallest rectangle that contains the two source rectangles.
+ * !#zh 返回一个包含两个指定矩形的最小矩形。
* @method rectUnion
* @param {Rect} rectA
* @param {Rect} rectB
* @return {Rect}
+ * @example
+ * var a = new cc.rect(0, 10, 20, 20);
+ * var b = new cc.rect(0, 10, 10, 10);
+ * cc.rectUnion(a, b); // return Rect {x: 0, y: 10, width: 20, height: 20};
*/
cc.rectUnion = function (rectA, rectB) {
var rect = cc.rect(0, 0, 0, 0);
@@ -427,11 +564,16 @@ cc.rectUnion = function (rectA, rectB) {
};
/**
- * Returns the overlapping portion of 2 rectangles.
+ * !#en Returns the overlapping portion of 2 rectangles.
+ * !#zh 返回 2 个矩形重叠的部分。
* @method rectUnion
* @param {Rect} rectA
* @param {Rect} rectB
* @return {Rect}
+ * @example
+ * var a = new cc.rect(0, 10, 20, 20);
+ * var b = new cc.rect(0, 10, 10, 10);
+ * cc.rectIntersection(a, b); // return Rect {x: 0, y: 10, width: 10, height: 10};
*/
cc.rectIntersection = function (rectA, rectB) {
var intersection = cc.rect(
diff --git a/cocos2d/core/value-types/CCSize.js b/cocos2d/core/value-types/CCSize.js
index 21b736bcf1..9acf29f62a 100644
--- a/cocos2d/core/value-types/CCSize.js
+++ b/cocos2d/core/value-types/CCSize.js
@@ -27,8 +27,18 @@ var ValueType = require('./CCValueType');
var JS = require('../platform/js');
/**
- * cc.Size is the class for size object, please do not use its constructor to create sizes, use {{#crossLink "cc/size:method"}}{{/crossLink}} alias function instead.
- * It will be deprecated soon, please use cc.Vec2 instead
+ * !#en
+ * cc.Size is the class for size object,
+ * please do not use its constructor to create sizes,
+ * use {{#crossLink "cc/size:method"}}{{/crossLink}} alias function instead.
+ * It will be deprecated soon, please use cc.Vec2 instead.
+ *
+ * !#zh
+ * cc.Size 是 size 对象的类。
+ * 请不要使用它的构造函数创建的 size,
+ * 使用 {{#crossLink "cc/size:method"}}{{/crossLink}} 别名函数。
+ * 它不久将被取消,请使用cc.Vec2代替。
+ *
* @class Size
*/
/**
@@ -49,7 +59,8 @@ JS.extend(Size, ValueType);
require('../platform/CCClass').fastDefine('cc.Size', Size, ['width', 'height']);
/**
- * return a Size object with width = 0 and height = 0.
+ * !#en return a Size object with width = 0 and height = 0.
+ * !#zh 返回与宽度 = 0 和高度 = 0 Size 的对象。
* @property ZERO
* @type {Size}
* @default new Size(0, 0)
@@ -62,17 +73,27 @@ JS.get(Size, 'ZERO', function () {
var proto = Size.prototype;
/**
+ * !#en TODO
+ * !#zh 克隆 size 对象。
* @method clone
* @return {Size}
+ * @example
+ * var a = new cc.size(10, 10);
+ * a.clone();// return Size {width: 0, height: 0};
*/
proto.clone = function () {
return new Size(this.width, this.height);
};
/**
+ * !#en TODO
+ * !#zh 当前 size 对象是否等于指定 size 对象。
* @method equals
* @param {Size} other
* @return {Boolean}
+ * @example
+ * var a = new cc.size(10, 10);
+ * a.equals(new cc.size(10, 10));// return true;
*/
proto.equals = function (other) {
return other &&
@@ -81,11 +102,22 @@ proto.equals = function (other) {
};
/**
+ * !#en TODO
+ * !#zh Rect 的线性插值。
* @method lerp
* @param {Rect} to
* @param {Number} ratio - the interpolation coefficient.
* @param {Size} [out] - optional, the receiving vector.
* @return {Size}
+ * @example
+ * var a = new cc.size(10, 10);
+ * var b = new cc.rect(50, 50, 100, 100);
+ * update (dt) {
+ * // method 1;
+ * var c = a.lerp(b, dt * 0.1);
+ * // method 2;
+ * a.lerp(b, dt * 0.1, c);
+ * }
*/
proto.lerp = function (to, ratio, out) {
out = out || new Size();
@@ -97,19 +129,27 @@ proto.lerp = function (to, ratio, out) {
};
/**
+ * !#en TODO
+ * !#zh Size 用字符串表示。
* @method toString
* @return {String}
+ * @example
+ * var a = new cc.size(10, 10);
+ * a.toString();// return "(10.00, 10.00)";
*/
proto.toString = function () {
return '(' + this.width.toFixed(2) + ', ' + this.height.toFixed(2) + ')';
};
/**
- * Helper function that creates a cc.Size.
+ * !#en
+ * Helper function that creates a cc.Size.
* Please use cc.p or cc.v2 instead, it will soon replace cc.Size.
- *
+ * !#zh
+ * 创建一个 cc.Size 帮助函数。
+ * 请使用 cc.p 或者是 cc.v2 代替,将很快取代 cc.Size。
* @method size
- * @param {Number|Size} w - width or a size object
+ * @param {Number|Size} w - width or a size object
* @param {Number} h - height
* @return {Size}
* @example {@link utils/api/engine/docs/cocos2d/core/value-types/CCSize/size.js}
@@ -119,11 +159,18 @@ cc.size = function (w, h) {
};
/**
- * Check whether a point's value equals to another.
+ * !#en Check whether a point's value equals to another.
+ * !#zh 检查 size 对象是否等于另一个。
* @method sizeEqualToSize
* @param {Size} size1
* @param {Size} size2
* @return {Boolean}
+ * @example
+ * var a = new cc.size(10, 10);
+ * var b = new cc.size(10, 10);
+ * cc.sizeEqualToSize(a, b);// return true;
+ * var b = new cc.size(5, 10);
+ * cc.sizeEqualToSize(a, b);// return false;
*/
cc.sizeEqualToSize = function (size1, size2) {
return (size1 && size2 && (size1.width === size2.width) && (size1.height === size2.height));
diff --git a/cocos2d/core/value-types/CCTypes.js b/cocos2d/core/value-types/CCTypes.js
index 6af48d93ec..e731cbecb0 100644
--- a/cocos2d/core/value-types/CCTypes.js
+++ b/cocos2d/core/value-types/CCTypes.js
@@ -25,7 +25,8 @@
****************************************************************************/
/**
- * the device accelerometer reports values for each axis in units of g-force.
+ * !#en the device accelerometer reports values for each axis in units of g-force.
+ * !#zh 设备重力传感器传递的各个轴的数据。
* @class Acceleration
* @constructor
*/
@@ -45,7 +46,8 @@ cc.Acceleration = function (x, y, z, timestamp) {
};
/**
- * Blend Function used for textures.
+ * !#en Blend Function used for textures.
+ * !#zh 用于纹理的混合函数。
* @class BlendFunc
* @Constructor
*/
@@ -187,7 +189,9 @@ cc.blendFuncDisable = cc.BlendFunc._disable;
* @constructor
*/
/**
- * @method FontDefinition
+ * !#en TODO
+ * !#zh 定义字体基本属性的结构体。
+ * @method FontDefinition
* @param {Object} properties - (OPTIONAL) Allow inline FontDefinition
* @return {FontDefinition}
*/
diff --git a/cocos2d/core/value-types/CCValueType.js b/cocos2d/core/value-types/CCValueType.js
index 1436a7d754..f327a009cc 100644
--- a/cocos2d/core/value-types/CCValueType.js
+++ b/cocos2d/core/value-types/CCValueType.js
@@ -26,7 +26,8 @@
var JS = require('../platform/js');
/**
- * The base class of all value types.
+ * !#en The base class of all value types.
+ * !#zh 所有 value 类型的基类。
* @class ValueType
* @constructor
*/
@@ -46,7 +47,8 @@ JS.mixin(ValueType.prototype, {
},
/**
- * Compares this object with the other one.
+ * !#en Compares this object with the other one.
+ * !#zh 当前对象是否等于指定对象。
* @method equals
* @param {ValueType} other
* @return {Boolean}
@@ -57,6 +59,8 @@ JS.mixin(ValueType.prototype, {
},
/**
+ * !#en TODO
+ * !#zh 用字符串表示。
* @method toString
* @return {string}
*/
@@ -65,8 +69,12 @@ JS.mixin(ValueType.prototype, {
},
/**
+ * !#en
* Linearly interpolates between this value to to value by ratio which is in the range [0, 1].
* When ratio = 0 returns this. When ratio = 1 return to. When ratio = 0.5 returns the average of this and to.
+ * !#zh
+ * 线性插值。
+ * 当 ratio = 0 返回此。当 ratio = 1 返回。当 ratio = 0.5 返回平均值的这个和。
* @method lerp
* @param {ValueType} to - the to value
* @param {number} ratio - the interpolation coefficient
diff --git a/cocos2d/core/value-types/CCVec2.js b/cocos2d/core/value-types/CCVec2.js
index a6cc5ad046..1d453873b7 100644
--- a/cocos2d/core/value-types/CCVec2.js
+++ b/cocos2d/core/value-types/CCVec2.js
@@ -28,16 +28,20 @@ var JS = require('../platform/js');
var FireClass = require('../platform/CCClass');
/**
- * Representation of 2D vectors and points.
+ * !#en Representation of 2D vectors and points.
+ * !#zh 代表 2D 向量和 points。
*
* @class Vec2
* @extends ValueType
* @constructor
*/
- /**
+/**
+ * !#en
* Constructor
* see {{#crossLink "cc/vec2:method"}}cc.v2{{/crossLink}} or {{#crossLink "cc/p:method"}}cc.p{{/crossLink}}
+ * !#zh
+ * 构造函数,可查看 {{#crossLink "cc/vec2:method"}}cc.v2{{/crossLink}} 或者 {{#crossLink "cc/p:method"}}cc.p{{/crossLink}}
* @method Vec2
* @param {number} [x=0]
* @param {number} [y=0]
@@ -67,6 +71,8 @@ JS.mixin(Vec2.prototype, {
},
/**
+ * !#en TODO
+ * !#zh 设置。
* @method set
* @param {Vec2} newValue - !#en new value to set. !#zh 要设置的新值
* @return {Vec2} returns this
@@ -79,6 +85,8 @@ JS.mixin(Vec2.prototype, {
},
/**
+ * !#en TODO
+ * !#zh 当前的向量是否与指定的向量相等。
* @method equals
* @param {Vec2} other
* @return {Boolean}
@@ -88,6 +96,8 @@ JS.mixin(Vec2.prototype, {
},
/**
+ * !#en TODO
+ * !#zh 用字符串表示。
* @method toString
* @return {string}
*/
@@ -99,6 +109,8 @@ JS.mixin(Vec2.prototype, {
},
/**
+ * !#en TODO
+ * !#zh 向量线性插值。
* @method lerp
* @param {Vec2} to
* @param {number} ratio - the interpolation coefficient
@@ -115,11 +127,15 @@ JS.mixin(Vec2.prototype, {
},
/**
- * Adds this vector. If you want to save result to another vector, use add() instead.
+ * !#en Adds this vector. If you want to save result to another vector, use add() instead.
+ * !#zh 当前向量加等于指定的向量。如果你想保存结果到另一个向量,使用 add() 代替。
* @method addSelf
* @param {Vec2} vector
* @return {Vec2} returns this
* @chainable
+ * @example
+ * var v = cc.v2(10, 10);
+ * v.addSelf(cc.v2(5, 5));// return Vec2 {x: 15, y: 15};
*/
addSelf: function (vector) {
this.x += vector.x;
@@ -128,11 +144,17 @@ JS.mixin(Vec2.prototype, {
},
/**
- * Adds two vectors, and returns the new result.
+ * !#en Adds two vectors, and returns the new result.
+ * !#zh 当前向量与指定向量进行加法运算,并返回新结果。
* @method add
* @param {Vec2} vector
* @param {Vec2} [out] - optional, the receiving vector
* @return {Vec2} the result
+ * @example
+ * var v = cc.v2(10, 10);
+ * v.add(cc.v2(5, 5)); // return Vec2 {x: 15, y: 15};
+ * var v1;
+ * v.add(cc.v2(5, 5), v1); // return Vec2 {x: 15, y: 15};
*/
add: function (vector, out) {
out = out || new Vec2();
@@ -142,11 +164,15 @@ JS.mixin(Vec2.prototype, {
},
/**
- * Subtracts one vector from this. If you want to save result to another vector, use sub() instead.
+ * !#en Subtracts one vector from this. If you want to save result to another vector, use sub() instead.
+ * !#zh 当前向量减等于指定的向量。如果你想保存结果到另一个向量,可使用 sub() 代替。
* @method subSelf
* @param {Vec2} vector
* @return {Vec2} returns this
* @chainable
+ * @example
+ * var v = cc.v2(10, 10);
+ * v.subSelf(cc.v2(5, 5));// return Vec2 {x: 5, y: 5};
*/
subSelf: function (vector) {
this.x -= vector.x;
@@ -155,11 +181,17 @@ JS.mixin(Vec2.prototype, {
},
/**
- * Subtracts one vector from this, and returns the new result.
+ * !#en Subtracts one vector from this, and returns the new result.
+ * !#zh 当前向量与指定向量进行减法运算,并返回新结果。
* @method sub
* @param {Vec2} vector
* @param {Vec2} [out] - optional, the receiving vector
* @return {Vec2} the result
+ * @example
+ * var v = cc.v2(10, 10);
+ * v.sub(cc.v2(5, 5)); // return Vec2 {x: 5, y: 5};
+ * var v1;
+ * v.sub(cc.v2(5, 5), v1); // return Vec2 {x: 5, y: 5};
*/
sub: function (vector, out) {
out = out || new Vec2();
@@ -169,11 +201,15 @@ JS.mixin(Vec2.prototype, {
},
/**
- * Multiplies this by a number. If you want to save result to another vector, use mul() instead.
+ * !#en Multiplies this by a number. If you want to save result to another vector, use mul() instead.
+ * !#zh 当前向量进行 num 倍数的乘法运算。如果你想结果保存到另一个向量,可使用 mul() 代替。
* @method mulSelf
* @param {number} num
* @return {Vec2} returns this
* @chainable
+ * @example
+ * var v = cc.v2(10, 10);
+ * v.mulSelf(5);// return Vec2 {x: 50, y: 50};
*/
mulSelf: function (num) {
this.x *= num;
@@ -182,11 +218,17 @@ JS.mixin(Vec2.prototype, {
},
/**
- * Multiplies by a number, and returns the new result.
+ * !#en Multiplies by a number, and returns the new result.
+ * !#zh 当前向量与指定向量进行乘法运算,并返回新结果。
* @method mul
* @param {number} num
* @param {Vec2} [out] - optional, the receiving vector
* @return {Vec2} the result
+ * @example
+ * var v = cc.v2(10, 10);
+ * v.mul(5); // return Vec2 {x: 50, y: 50};
+ * var v1;
+ * v.mul(5, v1); // return Vec2 {x: 50, y: 50};
*/
mul: function (num, out) {
out = out || new Vec2();
@@ -196,11 +238,15 @@ JS.mixin(Vec2.prototype, {
},
/**
- * Multiplies two vectors.
+ * !#en Multiplies two vectors.
+ * !#zh 当前向量与指定向量进行相乘。
* @method scaleSelf
* @param {Vec2} vector
* @return {Vec2} returns this
* @chainable
+ * @example
+ * var v = cc.v2(10, 10);
+ * v.scaleSelf(cc.v2(5, 5));// return Vec2 {x: 50, y: 50};
*/
scaleSelf: function (vector) {
this.x *= vector.x;
@@ -209,11 +255,17 @@ JS.mixin(Vec2.prototype, {
},
/**
- * Multiplies two vectors, and returns the new result.
+ * !#en Multiplies two vectors, and returns the new result.
+ * !#zh 当前向量与指定向量进行相乘,并返回新的结果。
* @method scale
* @param {Vec2} vector
* @param {Vec2} [out] - optional, the receiving vector
* @return {Vec2} the result
+ * @example
+ * var v = cc.v2(10, 10);
+ * v.scale(cc.v2(5, 5)); // return Vec2 {x: 50, y: 50};
+ * var v1;
+ * v.scale(cc.v2(5, 5), v1); // return Vec2 {x: 50, y: 50};
*/
scale: function (vector, out) {
out = out || new Vec2();
@@ -223,11 +275,15 @@ JS.mixin(Vec2.prototype, {
},
/**
- * Divides by a number. If you want to save result to another vector, use div() instead.
+ * !#en Divides by a number. If you want to save result to another vector, use div() instead.
+ * !#zh 当前向量与指定向量进行相除。如果你想结果保存到另一个向量,可使用 div() 代替。
* @method divSelf
* @param {Vec2} vector
* @return {Vec2} returns this
* @chainable
+ * @example
+ * var v = cc.v2(10, 10);
+ * v.divSelf(5); // return Vec2 {x: 2, y: 2};
*/
divSelf: function (num) {
this.x /= num;
@@ -236,11 +292,17 @@ JS.mixin(Vec2.prototype, {
},
/**
- * Divides by a number, and returns the new result.
+ * !#en Divides by a number, and returns the new result.
+ * !#zh 当前向量与指定向量进行相除,并返回新的结果。
* @method div
* @param {Vec2} vector
* @param {Vec2} [out] - optional, the receiving vector
* @return {Vec2} the result
+ * @example
+ * var v = cc.v2(10, 10);
+ * v.div(5); // return Vec2 {x: 2, y: 2};
+ * var v1;
+ * v.div(5, v1); // return Vec2 {x: 2, y: 2};
*/
div: function (num, out) {
out = out || new Vec2();
@@ -250,10 +312,14 @@ JS.mixin(Vec2.prototype, {
},
/**
- * Negates the components. If you want to save result to another vector, use neg() instead.
+ * !#en Negates the components. If you want to save result to another vector, use neg() instead.
+ * !#zh 当前向量进行取反。如果你想结果保存到另一个向量,可使用 neg() 代替。
* @method negSelf
* @return {Vec2} returns this
* @chainable
+ * @example
+ * var v = cc.v2(10, 10);
+ * v.negSelf(); // return Vec2 {x: -10, y: -10};
*/
negSelf: function () {
this.x = -this.x;
@@ -262,10 +328,15 @@ JS.mixin(Vec2.prototype, {
},
/**
- * Negates the components, and returns the new result.
+ * !#en Negates the components, and returns the new result.
+ * !#zh 当前向量进行取反,并返回新的结果。
* @method neg
* @param {Vec2} [out] - optional, the receiving vector
* @return {Vec2} the result
+ * @example
+ * var v = cc.v2(10, 10);
+ * var v1;
+ * v.neg(v1); // return Vec2 {x: -10, y: -10};
*/
neg: function (out) {
out = out || new Vec2();
@@ -275,48 +346,68 @@ JS.mixin(Vec2.prototype, {
},
/**
- * Dot product
+ * !#en Dot product
+ * !#zh 当前向量与指定向量进行点(积)乘。
* @method dot
* @param {Vec2} [vector]
* @return {number} the result
+ * @example
+ * var v = cc.v2(10, 10);
+ * v.dot(cc.v2(5, 5)); // return 100;
*/
dot: function (vector) {
return this.x * vector.x + this.y * vector.y;
},
/**
- * Cross product
+ * !#en Cross product
+ * !#zh 当前向量与指定向量进行点乘叉(积)乘。
* @method cross
* @param {Vec2} [vector]
* @return {number} the result
+ * @example
+ * var v = cc.v2(10, 10);
+ * v.cross(cc.v2(5, 5)); // return 0;
*/
cross: function (vector) {
return this.y * vector.x - this.x * vector.y;
},
/**
- * Returns the length of this vector.
+ * !#en Returns the length of this vector.
+ * !#zh 返回该向量的长度。
* @method mag
* @return {number} the result
+ * @example
+ * var v = cc.v2(10, 10);
+ * v.mag(); // return 14.142135623730951;
*/
mag: function () {
return Math.sqrt(this.x * this.x + this.y * this.y);
},
/**
- * Returns the squared length of this vector.
+ * !#en Returns the squared length of this vector.
+ * !#zh 返回该向量的长度平方。
* @method magSqr
* @return {number} the result
+ * @example
+ * var v = cc.v2(10, 10);
+ * v.magSqr(); // return 200;
*/
magSqr: function () {
return this.x * this.x + this.y * this.y;
},
/**
- * Make the length of this vector to 1.
+ * !#en Make the length of this vector to 1.
+ * !#zh 让这个向量的长度为1。
* @method normalizeSelf
* @return {Vec2} returns this
* @chainable
+ * @example
+ * var v = cc.v2(10, 10);
+ * v.normalizeSelf(); // return Vec2 {x: 0.7071067811865475, y: 0.7071067811865475};
*/
normalizeSelf: function () {
var magSqr = this.x * this.x + this.y * this.y;
@@ -336,12 +427,22 @@ JS.mixin(Vec2.prototype, {
},
/**
- * Returns this vector with a magnitude of 1.
- *
+ * !#en
+ * Returns this vector with a magnitude of 1.
+ *
* Note that the current vector is unchanged and a new normalized vector is returned. If you want to normalize the current vector, use normalizeSelf function.
+ * !#zh
+ * 返回向量的长度为 1。
+ *
+ * 注意,当前向量不变,并返回一个新的标准化向量。如果你想来标准化当前向量,可使用 normalizeSelf 函数。
* @method normalize
* @param {Vec2} [out] - optional, the receiving vector
* @return {Vec2} result
+ * @example
+ * var v = cc.v2(10, 10);
+ * v.normalize(); // return Vec2 {x: 0.7071067811865475, y: 0.7071067811865475};
+ * var v1;
+ * v.normalize(v1); // return Vec2 {x: 0.7071067811865475, y: 0.7071067811865475};
*/
normalize: function (out) {
out = out || new Vec2();
@@ -352,7 +453,8 @@ JS.mixin(Vec2.prototype, {
},
/**
- * Get angle in radian between this and vector
+ * !#en Get angle in radian between this and vector.
+ * !#zh 获取当前向量与指定向量之间的弧度角。
* @method angle
* @param {Vec2} vector
* @return {number} from 0 to Math.PI
@@ -373,7 +475,8 @@ JS.mixin(Vec2.prototype, {
},
/**
- * Get angle in radian between this and vector with direction
+ * !#en Get angle in radian between this and vector with direction.
+ * !#zh 获取当前向量与指定向量之间的弧度和方向向量。
* @method signAngle
* @param {Vec2} vector
* @return {number} from -MathPI to Math.PI
@@ -388,7 +491,8 @@ JS.mixin(Vec2.prototype, {
},
/**
- * rotate
+ * !#en rotate
+ * !#zh 旋转
* @method rotate
* @param {number} radians
* @param {Vec2} [out] - optional, the receiving vector
@@ -402,7 +506,8 @@ JS.mixin(Vec2.prototype, {
},
/**
- * rotate self
+ * !#en rotate self
+ * !#zh 旋转自身
* @method rotateSelf
* @param {number} radians
* @return {Vec2} returns this
@@ -429,7 +534,8 @@ JS.mixin(Vec2.prototype, {
// static
/**
- * return a Vec2 object with x = 1 and y = 1
+ * !#en return a Vec2 object with x = 1 and y = 1.
+ * !#zh 返回 x = 1 和 y = 1 的 Vec2 对象。
* @property ONE
* @type Vec2
* @static
@@ -439,7 +545,8 @@ JS.get(Vec2, 'ONE', function () {
});
/**
- * return a Vec2 object with x = 0 and y = 0
+ * !#en return a Vec2 object with x = 0 and y = 0.
+ * !#zh 返回 x = 0 和 y = 0 的 Vec2 对象。
* @property ZERO
* @type Vec2
* @static
@@ -449,7 +556,8 @@ JS.get(Vec2, 'ZERO', function () {
});
/**
- * return a Vec2 object with x = 0 and y = 1
+ * !#en return a Vec2 object with x = 0 and y = 1.
+ * !#zh 返回 x = 0 和 y = 1 的 Vec2 对象。
* @property up
* @type Vec2
* @static
@@ -459,7 +567,8 @@ JS.get(Vec2, 'UP', function () {
});
/**
- * return a Vec2 object with x = 1 and y = 0
+ * !#en return a Vec2 object with x = 1 and y = 0.
+ * !#zh 返回 x = 1 和 y = 0 的 Vec2 对象。
* @property RIGHT
* @type Vec2
* @static
@@ -476,18 +585,25 @@ cc.Vec2 = Vec2;
/**
- * The convenience method to create a new {{#crossLink "Vec2"}}cc.Vec2{{/crossLink}}.
+ * !#en The convenience method to create a new {{#crossLink "Vec2"}}cc.Vec2{{/crossLink}}.
+ * !#zh 通过该简便的函数进行创建 {{#crossLink "Vec2"}}cc.Vec2{{/crossLink}}
* @method v2
* @param {Number|Object} [x=0]
* @param {Number} [y=0]
* @return {Vec2}
+ * @example
+ * var v1 = cc.v2();
+ * var v2 = cc.v2(0, 0);
+ * var v3 = cc.v2(v2);
+ * var v4 = cc.v2({x: 100, y: 100});
*/
cc.v2 = function v2 (x, y) {
return new Vec2(x, y);
};
/**
- * The convenience method to creates a new {{#crossLink "Vec2"}}cc.Vec2{{/crossLink}}.
+ * !#en The convenience method to creates a new {{#crossLink "Vec2"}}cc.Vec2{{/crossLink}}.
+ * !#zh 通过该简便的函数进行创建 {{#crossLink "Vec2"}}cc.Vec2{{/crossLink}}
* @method p
* @param {Number|Object} [x=0] a Number or a size object
* @param {Number} [y=0]
@@ -504,7 +620,8 @@ cc.p = cc.v2;
// Functional style API, for backward compatibility
/**
- * Check whether a point's value equals to another
+ * !#en Check whether a point's value equals to another.
+ * !#zh 检查向量的值是否等于另一个
* @method pointEqualToPoint
* @param {Vec2} point1
* @param {Vec2} point2
diff --git a/docs/cocos2d/core/support/pAdd.js b/docs/cocos2d/core/support/pAdd.js
deleted file mode 100644
index a1f5e8d7a3..0000000000
--- a/docs/cocos2d/core/support/pAdd.js
+++ /dev/null
@@ -1,4 +0,0 @@
------------------
-cc.pAdd( cc.p(1,1), cc.p(2,2) ); // preferred cocos2d way
-cc.pAdd( cc.p(1,1), cc.p(2,2) ); // also ok but more verbose
-cc.pAdd( cc.cpv(1,1), cc.cpv(2,2) ); // mixing chipmunk and cocos2d (avoid)
diff --git a/docs/cocos2d/core/support/pCompOp.js b/docs/cocos2d/core/support/pCompOp.js
deleted file mode 100644
index 9facaccb9f..0000000000
--- a/docs/cocos2d/core/support/pCompOp.js
+++ /dev/null
@@ -1,3 +0,0 @@
---------------
-//For example: let's try to take the floor of x,y
-var p = cc.pCompOp(cc.p(10,10),Math.abs);
diff --git a/docs/cocos2d/core/value-types/CCColor/color.js b/docs/cocos2d/core/value-types/CCColor/color.js
index 86c4819aa4..ebba3138fb 100644
--- a/docs/cocos2d/core/value-types/CCColor/color.js
+++ b/docs/cocos2d/core/value-types/CCColor/color.js
@@ -1,7 +1,7 @@
-----------------------
// 1. All channels seperately as parameters
-var color1 = cc.color(255, 255, 255, 255);
+var color1 = cc.Color(255, 255, 255, 255);
// 2. Convert a hex string to a color
-var color2 = cc.color("#000000");
+var color2 = cc.Color("#000000");
// 3. An color object as parameter
-var color3 = cc.color({r: 255, g: 255, b: 255, a: 255});
+var color3 = cc.Color({r: 255, g: 255, b: 255, a: 255});
diff --git a/docs/cocos2d/core/value-types/CCColor/lerp.js b/docs/cocos2d/core/value-types/CCColor/lerp.js
new file mode 100644
index 0000000000..8692f31c83
--- /dev/null
+++ b/docs/cocos2d/core/value-types/CCColor/lerp.js
@@ -0,0 +1,12 @@
+// Converts a white color to a black one trough time.
+var oldColor = cc.Color.WHITE;
+// Method 2
+update: function (dt) {
+ var outColor = oldColor.lerp(Color.BLACK, dt * 0.1);
+ cc.log(outColor);
+}
+// Method 2
+update: function (dt) {
+ oldColor.lerp(Color.white, dt * 0.1, outColor);
+ cc.log(outColor);
+}
\ No newline at end of file
diff --git a/docs/cocos2d/core/value-types/CCColor/toCSS.js b/docs/cocos2d/core/value-types/CCColor/toCSS.js
new file mode 100644
index 0000000000..6415aa54c7
--- /dev/null
+++ b/docs/cocos2d/core/value-types/CCColor/toCSS.js
@@ -0,0 +1,6 @@
+var color = cc.Color.BLACK;
+color.toCSS(); // return "#000";
+color.toCSS("rgba"); // return "rgba(0,0,0,1.00)";
+color.toCSS("rgb"); // return "rgba(0,0,0)";
+color.toCSS("#rgb"); // return "#000";
+color.toCSS("#rrggbb"); // return "#000000";
\ No newline at end of file
diff --git a/docs/cocos2d/core/value-types/CCEnum/Enum.js b/docs/cocos2d/core/value-types/CCEnum/Enum.js
new file mode 100644
index 0000000000..78918c5d18
--- /dev/null
+++ b/docs/cocos2d/core/value-types/CCEnum/Enum.js
@@ -0,0 +1,23 @@
+Texture.WrapMode = cc.Enum({
+ Repeat: -1,
+ Clamp: -1
+});
+
+// Texture.WrapMode.Repeat == 0
+// Texture.WrapMode.Clamp == 1
+// Texture.WrapMode[0] == "Repeat"
+// Texture.WrapMode[1] == "Clamp"
+
+var FlagType = cc.Enum({
+ Flag1: 1,
+ Flag2: 2,
+ Flag3: 4,
+ Flag4: 8,
+});
+
+var AtlasSizeList = cc.Enum({
+ 128: 128,
+ 256: 256,
+ 512: 512,
+ 1024: 1024,
+});
\ No newline at end of file
diff --git a/docs/cocos2d/core/value-types/CCSize/size.js b/docs/cocos2d/core/value-types/CCSize/size.js
index d61e901452..d7fba0c2d7 100644
--- a/docs/cocos2d/core/value-types/CCSize/size.js
+++ b/docs/cocos2d/core/value-types/CCSize/size.js
@@ -1,4 +1,3 @@
------
var size1 = cc.size();
var size2 = cc.size(100,100);
var size3 = cc.size(size2);