Correct the Date.p.getTimezoneOffset() doc (#893)

* Correct the Date.p.getTimezoneOffset() doc

Fixes #665

* More precisely describe getTimezoneOffset()

* Clarify what "local time zone" means

* Update code comment to clarify effect of DST

files/en-us/web/javascript/reference/global_objects/date/gettimezoneoffset/index.html

@@ -10,68 +10,70 @@
 ---
 <div>{{JSRef}}</div>
 
-<p>The <strong><code>getTimezoneOffset()</code></strong> method returns the time zone
-  difference, in minutes, from current locale (host system settings) to UTC.</p>
+<p>The <strong><code>getTimezoneOffset()</code></strong> method returns the difference, in minutes, between a date as evaluated in the UTC time zone, and the same date as evaluated in the local time zone.</p>
 
 <div>{{EmbedInteractiveExample("pages/js/date-gettimezoneoffset.html")}}</div>
 
 <h2 id="Syntax">Syntax</h2>
 
-<pre class="brush: js"><var>dateObj</var>.getTimezoneOffset()</pre>
+<pre class="syntaxbox notranslate"><var>date</var>.getTimezoneOffset()</pre>
 
 <h3 id="Return_value">Return value</h3>
 
-<p>A number representing the time-zone offset, in minutes, from the date based on current
-  host system settings to UTC.</p>
+<p>The difference, in minutes, between <var>date</var>, as evaluated in the UTC time zone, and as evaluated in the local time zone.</p>
 
 <h2 id="Description">Description</h2>
 
-<p>The time-zone offset is the difference, in minutes, from local time to UTC.</p>
+<p><code><var>date</var>.getTimezoneOffset()</code> returns the difference, in minutes, between <var>date</var> as evaluated in the UTC time zone, and <var>date</var> as evaluated in the local time zone — that is, the time zone of the host system in which the browser is being used (if the code is run from the Web in a browser), or otherwise the host system of whatever JavaScript runtime (for example, a Node.js environment) the code is executed in.</p>
 
-<p>Note that this means that the offset is positive if the local timezone is behind UTC,
-  and negative if it is ahead. For example, for time zone UTC+10:00 (Australian Eastern
-  Standard Time, Vladivostok Time, Chamorro Standard Time), <code>-600</code> will be
-  returned.</p>
+<h3>Negative values and positive values</h3>
+
+<p>The number of minutes returned by <code>getTimezoneOffset()</code> is positive if the local time zone is behind UTC, and negative if the local time zone is ahead of UTC. For example, for UTC+10, <code>-600</code> will be returned.</li>
 
 <table class="standard-table">
-  <thead>
-    <tr>
-      <th scope="row">Current Locale</th>
-      <th scope="col">UTC-8</th>
-      <th scope="col">UTC</th>
-      <th scope="col">UTC+3</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <th scope="row">Return Value</th>
-      <td>480</td>
-      <td>0</td>
-      <td>-180</td>
-    </tr>
-  </tbody>
+ <thead>
+  <tr>
+   <th scope="row">Current time zone</th>
+   <th scope="col">UTC-8</th>
+   <th scope="col">UTC</th>
+   <th scope="col">UTC+3</th>
+  </tr>
+ </thead>
+ <tbody>
+  <tr>
+   <th scope="row">Return Value</th>
+   <td>480</td>
+   <td>0</td>
+   <td>-180</td>
+  </tr>
+ </tbody>
 </table>
 
-<p>The time zone offset returned is the one that applies for the Date that it's called on.
-</p>
+<h3>Varied results in Daylight Saving Time (DST) time zones</h3>
 
-<p>If the host system is configured for daylight saving, the offset will change depending
-  on the date and time that the Date represents and that daylight saving applies.</p>
+<p>In a time zone that annually shifts in and out of Daylight Saving Time (DST), the number of minutes returned by calling <code>getTimezoneOffset()</code> can vary.</p>
+<p>Consider a given local time zone and a date <var>date1</var> that are both in DST, and consider <var>minutes</var>, the number of minutes returned by calling <code><var>date1</var>.getTimezoneOffset()</code>; then:</li>
 
-<h2 id="Examples">Examples</h2>
+<ul>
+ <li>If the local time zone is currently in DST, but a given date <var>date2</var> is <em>not</em> in DST, then the number of minutes returned by <code><var>date2</var>.getTimezoneOffset()</code> is <var>minutes</var> ± 60.</li>
+ <li>If the local time zone is <em>not</em> currently in DST, but a given date <var>date3</var> is in DST, then the number of minutes returned by <code><var>date3</var>.getTimezoneOffset()</code> is <var>minutes</var> ± 60.</li>
+</ul>
+
+<p>In a time zone that doesn’t annually shift in and out of Daylight Saving Time (DST), the number of minutes returned by calling <code>getTimezoneOffset()</code> always returns the same number of minutes, regardless of the <var>date</var> instance it’s called from.</p>
 
-<h3 id="Using_getTimezoneOffset">Using getTimezoneOffset()</h3>
+<div class="notecard note">
+ <p><strong>Note:</strong> The above description is a simplification. In implementations, the {{InterWiki("wikipedia", "Daylight_saving_time#IANA_time_zone_database", "IANA time zone database")}} (tzdata) is used for precisely determining the effect of DST on the calculation of the time-zone difference.</p>
+</div>
 
-<pre class="brush: js">// Get current timezone offset for host device
-let x = new Date();
-let currentTimeZoneOffsetInHours = x.getTimezoneOffset() / 60;
-// 1
+<h2 id="Examples">Examples</h2>
 
-// Get timezone offset for International Labor Day (May 1) in 2016
-// Be careful, the Date() constructor uses 0-indexed months, so May is
-// represented with 4 (and not 5)
-let laborDay = new Date(2016, 4, 1)
-let laborDayOffset = laborDay.getTimezoneOffset() / 60;
+<pre class="brush: js notranslate">// Create a Date instance for the current time
+let currentLocalDate = new Date();
+// Create a Date instance for 03:24 GMT-0200 on May 1st in 2016
+let laborDay2016at0324GMTminus2 = new Date('May 1, 2016 03:24:00 GMT-0200');
+currentLocalDate.getTimezoneOffset() === laborDay2016at0324GMTminus2.getTimezoneOffset();
+// true, always, in any timezone that doesn't annually shift in and out of DST
+// false, sometimes, in any timezone that annually shifts in and out of DST
 </pre>
 
 <h2 id="Specifications">Specifications</h2>