Dimensions: values are non-integer and unreliable zoomed. Fixes gh-76, gh-103

Author: dmethvin

entries/height.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <entries>
   <desc>Get the current computed height for the first element in the set of matched elements or set the height of every matched element.</desc>
-  <entry type="method" name="height" return="Integer">
+  <entry type="method" name="height" return="Number">
     <title>.height()</title>
     <signature>
       <added>1.0</added>
@@ -22,6 +22,7 @@ $( document ).height(); // returns height of HTML document
         <p><strong>Note:</strong> Although <code>style</code> and <code>script</code> tags will report a value for <code>.width()</code> or <code>height()</code> when absolutely positioned and given <code>display:block</code>, it is strongly discouraged to call those methods on these tags. In addition to being a bad practice, the results may also prove unreliable.</p>
       </div>
     </longdesc>
+	<note id="dimensions-number" type="additional" data-title=".height()"/>
     <example>
       <desc>Show various heights.  Note the values are from the iframe so might be smaller than you expected.  The yellow highlight shows the iframe body.</desc>
       <code><![CDATA[

entries/innerHeight.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0"?>
-<entry type="method" name="innerHeight" return="Integer">
+<entry type="method" name="innerHeight" return="Number">
   <title>.innerHeight()</title>
   <signature>
     <added>1.2.6</added>
@@ -12,6 +12,7 @@
       <img src="/resources/0042_04_02.png"/>
     </p>
   </longdesc>
+	<note id="dimensions-number" type="additional" data-title=".innerHeight()"/>
   <example>
     <desc>Get the innerHeight of a paragraph.</desc>
     <code><![CDATA[

entries/innerWidth.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0"?>
-<entry type="method" name="innerWidth" return="Integer">
+<entry type="method" name="innerWidth" return="Number">
   <title>.innerWidth()</title>
   <signature>
     <added>1.2.6</added>
@@ -12,6 +12,7 @@
       <img src="/resources/0042_04_05.png"/>
     </p>
   </longdesc>
+	<note id="dimensions-number" type="additional" data-title=".innerWidth()"/>
   <example>
     <desc>Get the innerWidth of a paragraph.</desc>
     <code><![CDATA[

entries/offset.xml

@@ -15,7 +15,8 @@
         <p>While it is possible to get the coordinates of elements with <code>visibility:hidden</code> set, <code>display:none</code> is excluded from the rendering tree and thus has a position that is undefined.</p>
       </div>
     </longdesc>
-    <example>
+	<note id="dimensions-number" type="additional" data-title=".offset()"/>
+     <example>
       <desc>Access the offset of the second paragraph:</desc>
       <code><![CDATA[
 var p = $( "p:last" );
@@ -81,7 +82,7 @@ $( "*", document.body ).click(function( event ) {
     <signature>
       <added>1.4</added>
       <argument name="coordinates" type="PlainObject">
-        <desc>An object containing the properties <code>top</code> and <code>left</code>, which are integers indicating the new top and left coordinates for the elements.</desc>
+        <desc>An object containing the properties <code>top</code> and <code>left</code>, which are numbers indicating the new top and left coordinates for the elements.</desc>
       </argument>
     </signature>
     <signature>

entries/outerHeight.xml

@@ -1,20 +1,21 @@
 <?xml version="1.0"?>
-<entry type="method" name="outerHeight" return="Integer">
+<entry type="method" name="outerHeight" return="Number">
   <title>.outerHeight()</title>
   <signature>
     <added>1.2.6</added>
     <argument name="includeMargin" optional="true" type="Boolean">
       <desc>A Boolean indicating whether to include the element's margin in the calculation.</desc>
     </argument>
   </signature>
-  <desc>Get the current computed height for the first element in the set of matched elements, including padding, border, and optionally margin. Returns an integer (without "px") representation of the value or null if called on an empty set of elements.</desc>
+  <desc>Get the current computed height for the first element in the set of matched elements, including padding, border, and optionally margin. Returns a number (without "px") representation of the value or null if called on an empty set of elements.</desc>
   <longdesc>
     <p>The top and bottom padding and border are always included in the <code>.outerHeight()</code> calculation; if the <code>includeMargin</code> argument is set to <code>true</code>, the margin (top and bottom) is also included.</p>
     <p>This method is not applicable to <code>window</code> and <code>document</code> objects; for these, use <code><a href="/height/">.height()</a></code> instead.</p>
     <p class="image">
       <img src="/resources/0042_04_03.png"/>
     </p>
   </longdesc>
+	<note id="dimensions-number" type="additional" data-title=".outerHeight()"/>
   <example>
     <desc>Get the outerHeight of a paragraph.</desc>
     <code><![CDATA[

entries/outerWidth.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0"?>
-<entry type="method" name="outerWidth" return="Integer">
+<entry type="method" name="outerWidth" return="Number">
   <title>.outerWidth()</title>
   <signature>
     <added>1.2.6</added>
@@ -16,6 +16,7 @@
       <img src="/resources/0042_04_06.png"/>
     </p>
   </longdesc>
+	<note id="dimensions-number" type="additional" data-title=".outerWidth()"/>
   <example>
     <desc>Get the outerWidth of a paragraph.</desc>
     <code><![CDATA[

entries/position.xml

@@ -12,7 +12,8 @@
       <p><strong>Note:</strong> jQuery does not support getting the position coordinates of hidden elements or accounting for borders, margins, or padding set on the body element.</p>
     </div>
   </longdesc>
-  <example>
+	<note id="dimensions-number" type="additional" data-title=".position()"/>
+   <example>
     <desc>Access the position of the second paragraph:</desc>
     <code><![CDATA[
 var p = $( "p:first" );

entries/width.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <entries>
   <desc>Get the current computed width for the first element in the set of matched elements or set the width of every matched element.</desc>
-  <entry type="method" name="width" return="Integer">
+  <entry type="method" name="width" return="Number">
     <title>.width()</title>
     <signature>
       <added>1.0</added>
@@ -22,6 +22,7 @@ $( document ).width();
       </code></pre>
       <p>Note that <code>.width()</code> will always return the content width, regardless of the value of the CSS <code>box-sizing</code> property. As of jQuery 1.8, this may require retrieving the CSS width plus <code>box-sizing</code> property and then subtracting any potential border and padding on each element when the element has <code>box-sizing: border-box</code>. To avoid this penalty, use <code>.css( "width" )</code> rather than <code>.width()</code>.</p>
     </longdesc>
+	<note id="dimensions-number" type="additional" data-title=".width()"/>
     <example>
       <desc>Show various widths.  Note the values are from the iframe so might be smaller than you expected.  The yellow highlight shows the iframe body.</desc>
       <code><![CDATA[

notes.xsl

@@ -1,6 +1,9 @@
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
 <xsl:template name="note">
 	<xsl:choose>
+		<xsl:when test="@id = 'dimensions-number'">
+			The numbers returned by dimensions-related APIs, including <code><xsl:value-of select="@data-title"/></code>, may be fractional in some cases. Code should not assume it is an integer. Also, dimensions may be incorrect when the page is zoomed by the user; browsers do not expose an API to detect this condition.
+		</xsl:when>
 		<xsl:when test="@id = 'document-order'">
 			Selected elements are in the order of their appearance in the document.
 		</xsl:when>