Upgrade to ExtJS 4.0.7 - Released 10/19/2011

[extjs.git] / src / util / Region.js

diff --git a/src/util/Region.js b/src/util/Region.js
index 845ea85..a9512e8 100644 (file)
--- a/src/util/Region.js
+++ b/src/util/Region.js
@@ -13,14 +13,11 @@ If you are unsure which license is appropriate for your use, please contact the
 
 */
 /**
- * @class Ext.util.Region
- * @extends Object
+ * This class represents a rectangular region in X,Y space, and performs geometric
+ * transformations or tests upon the region.
  *
- * <p>This class represents a rectangular region in X,Y space, and performs geometric
- * transformations or tests upon the region.</p>
- * <p>This class may be used to compare the document regions occupied by elements.</p>
+ * This class may be used to compare the document regions occupied by elements.
  */
-
 Ext.define('Ext.util.Region', {
 
     /* Begin Definitions */
@@ -31,7 +28,7 @@ Ext.define('Ext.util.Region', {
         /**
          * @static
          * Retrieves an Ext.util.Region for a particular element.
-         * @param {Mixed} el An element ID, htmlElement or Ext.core.Element representing an element in the document.
+         * @param {String/HTMLElement/Ext.Element} el An element ID, htmlElement or Ext.Element representing an element in the document.
          * @returns {Ext.util.Region} region
          */
         getRegion: function(el) {
@@ -40,8 +37,8 @@ Ext.define('Ext.util.Region', {
 
         /**
          * @static
-         * Creates a Region from a "box" Object which contains four numeric properties <code>top</code>, <code>right</code>, <code>bottom</code> and <code>left</code>.
-         * @param {Object} o An object with <code>top</code>, <code>right</code>, <code>bottom</code> and <code>left</code> properties.
+         * Creates a Region from a "box" Object which contains four numeric properties `top`, `right`, `bottom` and `left`.
+         * @param {Object} o An object with `top`, `right`, `bottom` and `left` properties.
          * @return {Ext.util.Region} region The Region constructed based on the passed object
          */
         from: function(o) {
@@ -69,6 +66,7 @@ Ext.define('Ext.util.Region', {
     /**
      * Checks if this region completely contains the region that is passed in.
      * @param {Ext.util.Region} region
+     * @return {Boolean}
      */
     contains : function(region) {
         var me = this;
@@ -102,6 +100,7 @@ Ext.define('Ext.util.Region', {
     /**
      * Returns the smallest region that contains the current AND targetRegion.
      * @param {Ext.util.Region} region
+     * @return {Ext.util.Region} a new region
      */
     union : function(region) {
         var me = this,
@@ -116,6 +115,7 @@ Ext.define('Ext.util.Region', {
     /**
      * Modifies the current region to be constrained to the targetRegion.
      * @param {Ext.util.Region} targetRegion
+     * @return {Ext.util.Region} this
      */
     constrainTo : function(r) {
         var me = this,
@@ -133,6 +133,7 @@ Ext.define('Ext.util.Region', {
      * @param {Number} right right offset
      * @param {Number} bottom bottom offset
      * @param {Number} left left offset
+     * @return {Ext.util.Region} this
      */
     adjust : function(t, r, b, l) {
         var me = this;
@@ -145,8 +146,8 @@ Ext.define('Ext.util.Region', {
 
     /**
      * Get the offset amount of a point outside the region
-     * @param {String} axis optional
-     * @param {Ext.util.Point} p the point
+     * @param {String} [axis]
+     * @param {Ext.util.Point} [p] the point
      * @return {Ext.util.Offset}
      */
     getOutOfBoundOffset: function(axis, p) {
@@ -198,8 +199,8 @@ Ext.define('Ext.util.Region', {
 
     /**
      * Check whether the point / offset is out of bound
-     * @param {String} axis optional
-     * @param {Ext.util.Point/Number} p the point / offset
+     * @param {String} [axis]
+     * @param {Ext.util.Point/Number} [p] the point / offset
      * @return {Boolean}
      */
     isOutOfBound: function(axis, p) {
@@ -233,12 +234,13 @@ Ext.define('Ext.util.Region', {
         return (p < this.y || p > this.bottom);
     },
 
-    /*
+    /**
      * Restrict a point within the region by a certain factor.
-     * @param {String} axis Optional
-     * @param {Ext.util.Point/Ext.util.Offset/Object} p
-     * @param {Number} factor
+     * @param {String} [axis]
+     * @param {Ext.util.Point/Ext.util.Offset/Object} [p]
+     * @param {Number} [factor]
      * @return {Ext.util.Point/Ext.util.Offset/Object/Number}
+     * @private
      */
     restrict: function(axis, p, factor) {
         if (Ext.isObject(axis)) {
@@ -269,11 +271,12 @@ Ext.define('Ext.util.Region', {
         }
     },
 
-    /*
+    /**
      * Restrict an offset within the region by a certain factor, on the x-axis
      * @param {Number} p
-     * @param {Number} factor The factor, optional, defaults to 1
-     * @return
+     * @param {Number} [factor=1] The factor.
+     * @return {Number}
+     * @private
      */
     restrictX : function(p, factor) {
         if (!factor) {
@@ -289,10 +292,12 @@ Ext.define('Ext.util.Region', {
         return p;
     },
 
-    /*
+    /**
      * Restrict an offset within the region by a certain factor, on the y-axis
      * @param {Number} p
-     * @param {Number} factor The factor, optional, defaults to 1
+     * @param {Number} [factor] The factor, defaults to 1
+     * @return {Number}
+     * @private
      */
     restrictY : function(p, factor) {
         if (!factor) {
@@ -308,9 +313,10 @@ Ext.define('Ext.util.Region', {
         return p;
     },
 
-    /*
+    /**
      * Get the width / height of this region
      * @return {Object} an object with width and height properties
+     * @private
      */
     getSize: function() {
         return {
@@ -329,7 +335,7 @@ Ext.define('Ext.util.Region', {
 
     /**
      * Copy the values of another Region to this Region
-     * @param {Region} The region to copy from.
+     * @param {Ext.util.Region} p The region to copy from.
      * @return {Ext.util.Region} This Region
      */
     copyFrom: function(p) {
@@ -352,9 +358,9 @@ Ext.define('Ext.util.Region', {
 
     /**
      * Translate this region by the given offset amount
-     * @param {Ext.util.Offset/Object} offset Object containing the <code>x</code> and <code>y</code> properties.
+     * @param {Ext.util.Offset/Object} x Object containing the `x` and `y` properties.
      * Or the x value is using the two argument form.
-     * @param {Number} The y value unless using an Offset object.
+     * @param {Number} y The y value unless using an Offset object.
      * @return {Ext.util.Region} this This Region
      */
     translateBy: function(x, y) {