vanilla ckeditor-3.5.3

[ckeditor.git] / _source / core / dom / element.js

diff --git a/_source/core/dom/element.js b/_source/core/dom/element.js
index 18c56e6..2f3eb0a 100644 (file)
--- a/_source/core/dom/element.js
+++ b/_source/core/dom/element.js
@@ -307,6 +307,7 @@ CKEDITOR.tools.extend( CKEDITOR.dom.element.prototype,
 \r
                /**\r
                 * Moves the selection focus to this element.\r
+                * @function\r
                 * @param  {Boolean} defer Whether to asynchronously defer the\r
                 *              execution by 100 ms.\r
                 * @example\r
@@ -816,14 +817,15 @@ CKEDITOR.tools.extend( CKEDITOR.dom.element.prototype,
                },\r
 \r
                /**\r
-                * Indicates that the element has defined attributes.\r
+                * Checks if the element has any defined attributes.\r
+                * @function\r
                 * @returns {Boolean} True if the element has attributes.\r
                 * @example\r
-                * var element = CKEDITOR.dom.element.createFromHtml( '<div title="Test">Example</div>' );\r
-                * alert( <b>element.hasAttributes()</b> );  "true"\r
+                * var element = CKEDITOR.dom.element.createFromHtml( '&lt;div title="Test"&gt;Example&lt;/div&gt;' );\r
+                * alert( <b>element.hasAttributes()</b> );  // "true"\r
                 * @example\r
-                * var element = CKEDITOR.dom.element.createFromHtml( '<div>Example</div>' );\r
-                * alert( <b>element.hasAttributes()</b> );  "false"\r
+                * var element = CKEDITOR.dom.element.createFromHtml( '&lt;div&gt;Example&lt;/div&gt;' );\r
+                * alert( <b>element.hasAttributes()</b> );  // "false"\r
                 */\r
                hasAttributes :\r
                        CKEDITOR.env.ie && ( CKEDITOR.env.ie7Compat || CKEDITOR.env.ie6Compat ) ?\r
@@ -877,9 +879,9 @@ CKEDITOR.tools.extend( CKEDITOR.dom.element.prototype,
                                },\r
 \r
                /**\r
-                * Indicates whether a specified attribute is defined for this element.\r
+                * Checks if the specified attribute is defined for this element.\r
                 * @returns {Boolean} True if the specified attribute is defined.\r
-                * @param (String) name The attribute name.\r
+                * @param {String} name The attribute name.\r
                 * @example\r
                 */\r
                hasAttribute : function( name )\r
@@ -922,7 +924,12 @@ CKEDITOR.tools.extend( CKEDITOR.dom.element.prototype,
                },\r
 \r
                /**\r
-                * @param {Boolean} [inlineOnly=true] Allow only inline elements to be merged.\r
+                * Merges sibling elements that are identical to this one.<br>\r
+                * <br>\r
+                * Identical child elements are also merged. For example:<br>\r
+                * &lt;b&gt;&lt;i&gt;&lt;/i&gt;&lt;/b&gt;&lt;b&gt;&lt;i&gt;&lt;/i&gt;&lt;/b&gt; =&gt; &lt;b&gt;&lt;i&gt;&lt;/i&gt;&lt;/b&gt;\r
+                * @function\r
+                * @param {Boolean} [inlineOnly] Allow only inline elements to be merged. Defaults to "true".\r
                 */\r
                mergeSiblings : ( function()\r
                {\r
@@ -1554,9 +1561,12 @@ CKEDITOR.tools.extend( CKEDITOR.dom.element.prototype,
 \r
                /**\r
                 * Gets, sets and removes custom data to be stored as HTML5 data-* attributes.\r
-                * @name CKEDITOR.dom.element.data\r
-                * @param {String} name The name of the attribute, execluding the 'data-' part.\r
+                * @param {String} name The name of the attribute, excluding the 'data-' part.\r
                 * @param {String} [value] The value to set. If set to false, the attribute will be removed.\r
+                * @example\r
+                * element.data( 'extra-info', 'test' );   // appended the attribute data-extra-info="test" to the element\r
+                * alert( element.data( 'extra-info' ) );  // "test"\r
+                * element.data( 'extra-info', false );    // remove the data-extra-info attribute from the element\r
                 */\r
                data : function ( name, value )\r
                {\r
@@ -1588,11 +1598,12 @@ CKEDITOR.tools.extend( CKEDITOR.dom.element.prototype,
        }\r
 \r
        /**\r
-        * Update the element's size with box model awareness.\r
-        * @name CKEDITOR.dom.element.setSize\r
-        * @param {String} type [width|height]\r
+        * Sets the element size considering the box model.\r
+        * @name CKEDITOR.dom.element.prototype.setSize\r
+        * @function\r
+        * @param {String} type The dimension to set. It accepts "width" and "height".\r
         * @param {Number} size The length unit in px.\r
-        * @param isBorderBox Apply the {@param width} and {@param height} based on border box model.\r
+        * @param {Boolean} isBorderBox Apply the size based on the border box model.\r
         */\r
        CKEDITOR.dom.element.prototype.setSize = function( type, size, isBorderBox )\r
                {\r
@@ -1606,17 +1617,18 @@ CKEDITOR.tools.extend( CKEDITOR.dom.element.prototype,
                };\r
 \r
        /**\r
-        * Get the element's size, possibly with box model awareness.\r
-        * @name CKEDITOR.dom.element.getSize\r
-        * @param {String} type [width|height]\r
-        * @param {Boolean} contentSize Get the {@param width} or {@param height} based on border box model.\r
+        * Gets the element size, possibly considering the box model.\r
+        * @name CKEDITOR.dom.element.prototype.getSize\r
+        * @function\r
+        * @param {String} type The dimension to get. It accepts "width" and "height".\r
+        * @param {Boolean} isBorderBox Get the size based on the border box model.\r
         */\r
-       CKEDITOR.dom.element.prototype.getSize = function( type, contentSize )\r
+       CKEDITOR.dom.element.prototype.getSize = function( type, isBorderBox )\r
                {\r
                        var size = Math.max( this.$[ 'offset' + CKEDITOR.tools.capitalize( type )  ],\r
                                this.$[ 'client' + CKEDITOR.tools.capitalize( type )  ] ) || 0;\r
 \r
-                       if ( contentSize )\r
+                       if ( isBorderBox )\r
                                size -= marginAndPaddingSize.call( this, type );\r
 \r
                        return size;\r