doc: Merge/udpate old Element.Methods.getDimensions (et al) docs into…

… source [prototypejs#77 state:fixed_in_branch]

src/dom/dom.js

@@ -1663,6 +1663,22 @@ Element.Methods = {
    *  Element.getHeight(@element) -> Number
    *
    *  Returns the height of `element`.
+   *  
+   *  This method returns correct values on elements whose display is set to
+   *  `none` either in an inline style rule or in an CSS stylesheet.
+   *  
+   *  For performance reasons, if you need to query both width _and_ height of
+   *  `element`, you should consider using [[Element.getDimensions]] instead.
+   *  
+   *  Note that the value returned is a _number only_ although it is
+   *  _expressed in pixels_.
+   *  
+   *  ##### Examples
+   *  
+   *      <div id="rectangle" style="font-size: 10px; width: 20em; height: 10em"></div>
+   *  
+   *      $('rectangle').getHeight();
+   *      // -> 100
   **/
   getHeight: function(element) {
     return Element.getDimensions(element).height;
@@ -1672,6 +1688,22 @@ Element.Methods = {
    *  Element.getWidth(@element) -> Number
    *
    *  Returns the width of `element`.
+   *  
+   *  This method returns correct values on elements whose display is set to
+   *  `none` either in an inline style rule or in an CSS stylesheet.
+   *  
+   *  For performance reasons, if you need to query both width _and_ height of
+   *  `element`, you should consider using [[Element.getDimensions]] instead.
+   *  
+   *  Note that the value returned is a _number only_ although it is
+   *  _expressed in pixels_.
+   *  
+   *  ##### Examples
+   *  
+   *      <div id="rectangle" style="font-size: 10px; width: 20em; height: 10em"></div>
+   *  
+   *      $('rectangle').getWidth();
+   *      // -> 200
   **/
   getWidth: function(element) {
     return Element.getDimensions(element).width;
@@ -2059,6 +2091,30 @@ Element.Methods = {
    *
    *  Finds the computed width and height of `element` and returns them as
    *  key/value pairs of an object.
+   *  
+   *  This method returns correct values on elements whose display is set to
+   *  `none` either in an inline style rule or in an CSS stylesheet.
+   *  
+   *  In order to avoid calling the method twice, you should consider caching
+   *  the values returned in a variable as shown below. If you only need
+   *  `element`'s width or height, consider using [[Element.getWidth]] or
+   *  [[Element.getHeight]] instead.
+   *  
+   *  Note that all values are returned as _numbers only_ although they are
+   *  _expressed in pixels_.
+   *  
+   *  ##### Examples
+   *  
+   *      <div id="rectangle" style="font-size: 10px; width: 20em; height: 10em"></div>
+   *  
+   *      var dimensions = $('rectangle').getDimensions();
+   *      // -> {width: 200, height: 100}
+   *      
+   *      dimensions.width;
+   *      // -> 200
+   *      
+   *      dimensions.height;
+   *      // -> 100
   **/
   getDimensions: function(element) {
     element = $(element);