From 4015b022adfed04fe71bc03fe31c3da4ff29aa54 Mon Sep 17 00:00:00 2001 From: Jonathan Puckey Date: Fri, 27 May 2011 18:43:27 +0200 Subject: [PATCH] Docs: use @true tag in boolean return descriptions and add Key.isDown param options. --- src/basic/Point.js | 19 +++++++---------- src/basic/Rectangle.js | 13 ++++++------ src/basic/Size.js | 5 ++--- src/color/Color.js | 4 ++-- src/color/Gradient.js | 2 +- src/color/GradientColor.js | 2 +- src/item/Item.js | 43 +++++++++++++++++--------------------- src/path/Curve.js | 4 ++-- src/ui/Key.js | 6 +++++- 9 files changed, 46 insertions(+), 52 deletions(-) diff --git a/src/basic/Point.js b/src/basic/Point.js index a62c05f4..8354c524 100644 --- a/src/basic/Point.js +++ b/src/basic/Point.js @@ -521,8 +521,7 @@ var Point = this.Point = Base.extend({ * Checks whether the point is inside the boundaries of the rectangle. * * @param {Rectangle} rect the rectangle to check against - * @returns {boolean} true if the point is inside the rectangle, false - * otherwise. + * @returns {boolean} {@true if the point is inside the rectangle} */ isInside: function(rect) { return rect.contains(this); @@ -533,8 +532,7 @@ var Point = this.Point = Base.extend({ * * @param {Point} point the point to check against * @param {number} tolerance the maximum distance allowed - * @returns {boolean} true if it is within the given distance, false - * otherwise. + * @returns {boolean} {@true if it is within the given distance} */ isClose: function(point, tolerance) { return this.getDistance(point) < tolerance; @@ -545,7 +543,7 @@ var Point = this.Point = Base.extend({ * another vector. * * @param {Point} point the vector to check against - * @returns {boolean} true if it is parallel, false otherwise. + * @returns {boolean} {@true it is parallel} */ isColinear: function(point) { return this.cross(point) < Numerical.TOLERANCE; @@ -556,7 +554,7 @@ var Point = this.Point = Base.extend({ * (perpendicular) to another vector. * * @param {Point} point the vector to check against - * @returns {boolean} true if it is orthogonal, false otherwise. + * @returns {boolean} {@true it is orthogonal} */ isOrthogonal: function(point) { return this.dot(point) < Numerical.TOLERANCE; @@ -565,7 +563,7 @@ var Point = this.Point = Base.extend({ /** * Checks if this point has both the x and y coordinate set to 0. * - * @returns {boolean} true if both x and y are 0, false otherwise. + * @returns {boolean} {@true both x and y are 0} */ isZero: function() { return this.x == 0 && this.y == 0; @@ -575,8 +573,7 @@ var Point = this.Point = Base.extend({ * Checks if this point has an undefined value for at least one of its * coordinates. * - * @returns {boolean} true if either x or y are not a number, false - * otherwise. + * @returns {boolean} {@true if either x or y are not a number} */ isNaN: function() { return isNaN(this.x) || isNaN(this.y); @@ -628,11 +625,11 @@ var Point = this.Point = Base.extend({ /** * This property is only present if the point is an anchor or control point * of a {@link Segment} or a {@link Curve}. In this case, it returns - * true if it is selected, false otherwise + * {@true it is selected} * * @name Point#selected * @property - * @return {boolean} true if the point is selected, false otherwise + * @return {boolean} {@true the point is selected} */ statics: { diff --git a/src/basic/Rectangle.js b/src/basic/Rectangle.js index fabaab43..5f5fa0be 100644 --- a/src/basic/Rectangle.js +++ b/src/basic/Rectangle.js @@ -337,7 +337,7 @@ var Rectangle = this.Rectangle = Base.extend({ }, /** - * @return {boolean} true if the rectangle is empty, false otherwise. + * @return {boolean} {@true the rectangle is empty} */ isEmpty: function() { return this.width == 0 || this.height == 0; @@ -363,16 +363,15 @@ var Rectangle = this.Rectangle = Base.extend({ * @name Rectangle#contains^2 * @function * @param {Point} point the specified point - * @return {boolean} true if the point is inside the rectangle's - * boundary, false otherwise + * @return {boolean} {@true if the point is inside the rectangle's boundary} */ /** * Tests if the interior of the rectangle entirely contains the specified * rectangle. * * @param {Rectangle} rect The specified rectangle - * @return {boolean} true if the rectangle entirely contains the - * specified rectangle, false otherwise + * @return {boolean} {@true if the rectangle entirely contains the specified + * rectangle} */ contains: function(rect) { if (rect.width !== undefined) { @@ -392,8 +391,8 @@ var Rectangle = this.Rectangle = Base.extend({ * another rectangle. * * @param {Rectangle} rect the specified rectangle - * @return {boolean} true if the rectangle and the specified rectangle - * intersect each other, false otherwise + * @return {boolean} {@true if the rectangle and the specified rectangle + * intersect each other} */ intersects: function(rect) { rect = Rectangle.read(arguments); diff --git a/src/basic/Size.js b/src/basic/Size.js index 5ce1ea6d..1e95497b 100644 --- a/src/basic/Size.js +++ b/src/basic/Size.js @@ -287,7 +287,7 @@ var Size = this.Size = Base.extend({ * {@grouptitle Tests} * Checks if this size has both the width and height set to 0. * - * @return {boolean} true if both width and height are 0, false otherwise. + * @return {boolean} {@true both width and height are 0} */ isZero: function() { return this.width == 0 && this.width == 0; @@ -296,8 +296,7 @@ var Size = this.Size = Base.extend({ /** * Checks if the width or the height of the size are NaN. * - * @return {boolean} true if the width or height of the size are NaN, false - * otherwise. + * @return {boolean} {@true if the width or height of the size are NaN} */ isNaN: function() { return isNaN(this.width) || isNaN(this.height); diff --git a/src/color/Color.js b/src/color/Color.js index 3d118c60..bffcce2a 100644 --- a/src/color/Color.js +++ b/src/color/Color.js @@ -300,7 +300,7 @@ var Color = this.Color = Base.extend(new function() { /** * Checks if the color has an alpha value. * - * @return true if the color has an alpha value, false otherwise. + * @return {@true if the color has an alpha value} */ hasAlpha: function() { return this._alpha != null; @@ -311,7 +311,7 @@ var Color = this.Color = Base.extend(new function() { * same as those of the supplied one. * * @param obj the GrayColor to compare with - * @return true if the GrayColor is the same, false otherwise. + * @return {@true if the GrayColor is the same} */ equals: function(color) { if (color && color._colorType === this._colorType) { diff --git a/src/color/Gradient.js b/src/color/Gradient.js index 04ac4f75..968831f6 100644 --- a/src/color/Gradient.js +++ b/src/color/Gradient.js @@ -72,7 +72,7 @@ var Gradient = this.Gradient = Base.extend({ * Checks whether the gradient is equal to the supplied gradient. * * @param {Gradient} gradient - * @return {boolean} true if they are equal, false otherwise + * @return {boolean} {@true they are equal} */ equals: function(gradient) { if (gradient.type != this.type) diff --git a/src/color/GradientColor.js b/src/color/GradientColor.js index 5e568345..d3afb722 100644 --- a/src/color/GradientColor.js +++ b/src/color/GradientColor.js @@ -128,7 +128,7 @@ var GradientColor = this.GradientColor = Color.extend({ * supplied one. * * @param {GradientColor} color - * @return true if the GradientColor is the same, false otherwise + * @return {@true the GradientColor is the same} */ equals: function(color) { return color == this || color && color._colorType === this._colorType diff --git a/src/item/Item.js b/src/item/Item.js index f3c99c74..f7400daf 100644 --- a/src/item/Item.js +++ b/src/item/Item.js @@ -177,7 +177,7 @@ var Item = this.Item = Base.extend({ * path.selected = true; // Select the path * console.log(project.selectedItems.length) // 1 * - * @type boolean true if the item is selected, false otherwise + * @type boolean {@true the item is selected} * @bean */ isSelected: function() { @@ -231,7 +231,7 @@ var Item = this.Item = Base.extend({ * console.log(path.visible) // true * path.visible = false; // Hides the path * - * @type boolean true if the item is visible, false otherwise + * @type boolean {@true the item is visible} * @default true */ visible: true, @@ -455,7 +455,7 @@ var Item = this.Item = Base.extend({ * Removes the item from the project. If the item has children, they are also * removed. * - * @return {boolean} true if the item was removed, false otherwise + * @return {boolean} {@true the item was removed} */ remove: function() { if (this.isSelected()) @@ -466,7 +466,7 @@ var Item = this.Item = Base.extend({ /** * Removes all of the item's children (if any). * - * @return {boolean} true if removing was successful, false otherwise + * @return {boolean} {@true removing was successful} */ removeChildren: function() { var removed = false; @@ -535,7 +535,7 @@ var Item = this.Item = Base.extend({ /** * Reverses the order of this item's children * - * @return {boolean} true if the children were removed, false otherwise. + * @return {boolean} {@true the children were removed} */ reverseChildren: function() { if (this._children) { @@ -575,7 +575,7 @@ var Item = this.Item = Base.extend({ * {@grouptitle Tests} * Checks if the item contains any children items. * - * @return {boolean} true if it has one or more children, false otherwise. + * @return {boolean} {@true it has one or more children} */ hasChildren: function() { return this._children && this._children.length > 0; @@ -586,8 +586,8 @@ var Item = this.Item = Base.extend({ /** * Checks whether the item is editable. * - * @return {boolean} true when neither the item, nor its parents are - * locked or hidden, false otherwise. + * @return {boolean} {@true when neither the item, nor its parents are + * locked or hidden} * @ignore */ isEditable: function() { @@ -603,7 +603,7 @@ var Item = this.Item = Base.extend({ /** * Checks whether the item is valid, i.e. it hasn't been removed. * - * @return {boolean} true if the item is valid, false otherwise. + * @return {boolean} {@true the item is valid} */ // TODO: isValid / checkValid @@ -612,8 +612,7 @@ var Item = this.Item = Base.extend({ * of the project. * * @param {Item} item The item to check against - * @return {boolean} true if it is above the specified item, false - * otherwise. + * @return {boolean} {@true if it is above the specified item} */ // TODO: isAbove @@ -622,8 +621,7 @@ var Item = this.Item = Base.extend({ * the project. * * @param {Item} item The item to check against - * @return {boolean} true if it is below the specified item, false - * otherwise. + * @return {boolean} {@true if it is below the specified item} */ // TODO: isBelow @@ -632,8 +630,7 @@ var Item = this.Item = Base.extend({ * Checks whether the specified item is the parent of the item. * * @param {Item} item The item to check against - * @return {boolean} true if it is the parent of the item, false - * otherwise. + * @return {boolean} {@true if it is the parent of the item} */ isParent: function(item) { return this._parent == item; @@ -643,7 +640,7 @@ var Item = this.Item = Base.extend({ * Checks whether the specified item is a child of the item. * * @param {Item} item The item to check against - * @return {boolean} true if it is a child of the item, false otherwise. + * @return {boolean} {@true it is a child of the item} */ isChild: function(item) { return item._parent == this; @@ -653,8 +650,7 @@ var Item = this.Item = Base.extend({ * Checks if the item is contained within the specified item. * * @param {Item} item The item to check against - * @return {boolean} true if it is inside the specified item, false - * otherwise. + * @return {boolean} {@true if it is inside the specified item} */ isDescendant: function(item) { var parent = this; @@ -669,8 +665,8 @@ var Item = this.Item = Base.extend({ * Checks if the item is an ancestor of the specified item. * * @param {Item} item the item to check against - * @return {boolean} true if the item is an ancestor of the specified - * item, false otherwise. + * @return {boolean} {@true if the item is an ancestor of the specified + * item} */ isAncestor: function(item) { var parent = item; @@ -685,8 +681,7 @@ var Item = this.Item = Base.extend({ * Checks whether the item is grouped with the specified item. * * @param {Item} item - * @return {boolean} true if the items are grouped together, false - * otherwise. + * @return {boolean} {@true if the items are grouped together} */ isGroupedWith: function(item) { var parent = this._parent; @@ -1082,7 +1077,7 @@ var Item = this.Item = Base.extend({ * * @function * @param {Item} item The item above which it should be moved - * @return {boolean} true if it was moved, false otherwise + * @return {boolean} {@true it was moved} */ moveAbove: move(true), @@ -1091,7 +1086,7 @@ var Item = this.Item = Base.extend({ * * @function * @param {Item} item the item below which it should be moved - * @return {boolean} true if it was moved, false otherwise + * @return {boolean} {@true it was moved} */ moveBelow: move(false) }; diff --git a/src/path/Curve.js b/src/path/Curve.js index d55f4215..a17ed30f 100644 --- a/src/path/Curve.js +++ b/src/path/Curve.js @@ -234,7 +234,7 @@ var Curve = this.Curve = Base.extend({ * Checks if this curve is linear, meaning it does not define any curve * handle. - * @return {boolean} true if the curve is linear, false otherwise. + * @return {boolean} {@true the curve is linear} */ isLinear: function() { return this._segment1._handleOut.isZero() @@ -246,7 +246,7 @@ var Curve = this.Curve = Base.extend({ /** * @param {number} length * @param {number} [start] - * @return {boolean} true if the curve is linear, false otherwise. + * @return {boolean} {@true the curve is linear} */ getParameter: function(length, start) { var args = this.getCurveValues(); diff --git a/src/ui/Key.js b/src/ui/Key.js index af4417d5..34b2c6a5 100644 --- a/src/ui/Key.js +++ b/src/ui/Key.js @@ -144,7 +144,11 @@ var Key = this.Key = new function() { * console.log('The shift key is currently pressed.') * } * } - * @return {boolean} true if the key is pressed, false otherwise + * + * @param {string} key One of: 'backspace', 'enter', 'shift', 'control', + * 'option', 'pause', 'caps-lock', 'escape', 'space', 'end', 'home', + * 'left', 'up', 'right', 'down', 'delete', 'command' + * @return {boolean} {@true if the key is pressed} */ isDown: function(key) { return !!keyMap[key];