Edits from tc39/proposal-temporal#1449

files/en-us/web/javascript/reference/global_objects/temporal/calendar/dateuntil/index.html

@@ -9,7 +9,7 @@
 ---
 {{JSRef}}
 
-<p class="summary"><span class="seoSummary">The <strong><code>dateUntil()</code></strong> method provides a way to find the span of time between two datetimes in the calendar's reckoning.</span>  This method does not need to be called directly except in specialized code. It is called indirectly when using the <code>until()</code> and <code>since()</code> methods of the <code>{{jsxref('Temporal.PlainDateTime','Temporal.PlainDateTime')}}</code>, <code>{{jsxref('Temporal.PlainDate','Temporal.PlainDate')}}</code>, and <code>{{jsxref('Temporal.PlainYearMonth','Temporal.PlainYearMonth')}}</code> classes.</p>
+<p class="summary"><span class="seoSummary">The <strong><code>dateUntil()</code></strong> method provides a way to find the span of time between two datetimes in the calendar's reckoning.</span>  This method does not need to be called directly except in specialized code. It is called indirectly when using the <code>until()</code> and <code>since()</code> methods of the <code>{{jsxref('Temporal.PlainDateTime','Temporal.PlainDateTime')}}</code>, <code>{{jsxref('Temporal.PlainDate','Temporal.PlainDate')}}</code>, and <code>{{jsxref('Temporal.PlainYearMonth','Temporal.PlainYearMonth')}}</code> classes, and from a number of other methods.</p>
 
 
 <h2 id="syntax">Syntax</h2>

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

@@ -12,7 +12,7 @@
 ---
 <div>{{JSRef}}</div>
 
-<p class="summary"><span class="seoSummary">The <strong>Temporal API</strong> provides an interface for representing dates and times, as well as calculating precise spans of time.</span> Much of it will seem familiar to anyone who has used {{jsxref('Date','Date')}}, but the Temporal API provides a far more powerful and flexible feature set, including built-in understanding of time zones, Daylight Saving status, usage of different calendars, and up to nanosecond precision.</p>
+<p class="summary"><span class="seoSummary">The <strong>Temporal API</strong> provides an interface for representing dates and times, as well as calculating precise spans of time.</span> Much of it will seem familiar to anyone who has used {{jsxref('Date','Date')}}, but the Temporal API provides a far more powerful and flexible feature set, including built-in understanding of time zones, Daylight Saving status, usage of different calendars, and up to nanosecond precision.  By providing separate ECMAScript classes for date-only, time-only, and other scoped use cases, Temporal makes code more readable and prevents bugs caused by incorrectly assuming 0, UTC, or a local time zone for values that are actually unknown.</p>
 
 <h2 id="objects">Built-In Objects</h2>
 

files/en-us/web/javascript/reference/global_objects/temporal/plaintime/compare/index.html

@@ -16,6 +16,9 @@
 <p class="summary"><span class="seoSummary">The <strong><code>compare()</code></strong> static method compares two times and returns an integer indicating which comes before the other.</span></p>
 <p>If you don't care about the order in which the two times occur, but instead merely want to know if they're the same or not, use <code>{{jsxref('Temporal/PlainTime/equals','Temporal.PlainTime.equals()')}}</code> instead.</p>
 
+<p>Note that time zone offset transitions, such as when Daylight Saving Time starts or ends, can produce unexpected results when comparing times.  This is because in those situations, clock times can be skipped or repeated.
+Therefore, <code>{{jsxref('Temporal.ZonedDateTime.compare','Temporal.ZonedDateTime.compare')}}</code> (not <code>Temporal.PlainTime.compare</code>) should be used if the caller's actual intent is to compare specific instants; e.g., the arrivals of two airplane flights.</p>
+
 
 <h2 id="syntax">Syntax</h2>
 
@@ -61,3 +64,26 @@ <h2 id="examples">Examples</h2>
 sorted = [one, two, three].sort(Temporal.PlainTime.compare);
 sorted.join(' | '); // => "01:24:00 | 01:24:05 | 03:24:00"
 </pre>
+
+<p>The following examples demonstrate differences between <code>Temporal.PlainTime.compare</code> and <code>{{jsxref('Temporal.ZonedDateTime.compare','Temporal.ZonedDateTime.compare')}}</code>.</p>
+
+<pre class="brush: js">
+// Backward transitions will repeat clock times
+zdtDst = Temporal.ZonedDateTime.from('2020-11-01T01:45-07:00[America/Los_Angeles]');
+zdtStandard = Temporal.ZonedDateTime.from('2020-11-01T01:30-08:00[America/Los_Angeles]');
+// The "first" 1:45 (in Daylight Time) is earlier than the "second" 1:30 (in Standard Time)
+Temporal.ZonedDateTime.compare(zdtDst, zdtStandard); // => -1
+// 1:45 is later than 1:30 when looking at a wall clock
+Temporal.PlainTime.compare(zdtDst, zdtStandard); // => 1
+
+// Forward transitions will skip clock times. Skipped times will be disambiguated.
+zdtBase = Temporal.ZonedDateTime.from('2020-03-08[America/Los_Angeles]');
+timeSkipped = Temporal.PlainTime.from('02:30');
+timeValid = Temporal.PlainTime.from('03:30');
+zdtSkipped = zdtBase.withPlainTime(timeSkipped);
+zdtValid = zdtBase.withPlainTime(timeValid);
+// The skipped time 2:30AM is disambiguated to 3:30AM, so the instants are equal
+Temporal.ZonedDateTime.compare(zdtSkipped, zdtValid); // => 0
+// 2:30 is earlier than 3:30 on a wall clock
+Temporal.PlainTime.compare(timeSkipped, timeValid); // => -1
+</pre>

files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/offset/index.html

@@ -23,7 +23,7 @@ <h2 id="syntax">Syntax</h2>
 
 <h3 id="value">Value</h3>
 
-<p>An integer.</p>
+<p>A string.</p>
 
 
 <h2 id="examples">Examples</h2>