comments

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

@@ -15,7 +15,7 @@
 <h2 id="syntax">Syntax</h2>
 
 <pre class="brush: js">
-var positivDuration = duration.abs();
+var positiveDuration = duration.abs();
 </pre>
 
 

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

@@ -20,7 +20,7 @@ <h2 id="syntax">Syntax</h2>
 
 <h3 id="parameters">Parameters</h3>
 
-<p>All parameters are {{optional_inline}} and specified as integers.  Any missing or <code>undefined</code> numerical arguments are taken to be zero.  Any non-integer numerical values is truncated to the nearest integer, towards zero. Non-zero values must all have the same sign.</p>
+<p>All parameters are {{optional_inline}} and specified as integers.  Any missing or <code>undefined</code> numerical arguments are taken to be zero.  Any non-integer numerical value is truncated to the nearest integer, towards zero. Non-zero values must all have the same sign.</p>
 
 <ul>
 	<li><code>years</code> – A number of years.</li>

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

@@ -15,7 +15,7 @@
 <h2 id="syntax">Syntax</h2>
 
 <pre class="brush: js">
-var invertedTime = time.negated();
+var invertedDuration = duration.negated();
 </pre>
 
 

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

@@ -19,7 +19,7 @@
 <h2 id="syntax">Syntax</h2>
 
 <pre class="brush: js">
-var newTime = duration.round(<var>options</var>);
+var newDuration = duration.round(<var>options</var>);
 </pre>
 
 <h3 id="parameters">Parameters</h3>

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

@@ -42,9 +42,6 @@ <h3 id="parameters">Parameters</h3>
 <dt><code>'reject'</code></dt>
 <dd>Out-of-range values will cause the function to throw a <code>RangeError</code>.</dd>
 </dl>
-<div class="note">
-<strong>Note:</strong> The <code>overflow</code> option has no effect in the default ISO calendar, because a year is always 12 months and therefore not ambiguous. However, <code>overflow</code> may have an effect in calendars where years can be different numbers of months.</p>
-</div>
 </dd>
 </dl>
 </dd>

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

@@ -32,7 +32,7 @@ <h3 id="parameters">Parameters</h3>
 <li>A <code>day</code> property.</li>
 </ul>
 <p>The object may also contain a <code>calendar</code> property; if omitted, the ISO 8601 calendar is used.  The default value of any omitted date-related property (e.g., {{jsxref('Temporal.PlainDateTime/era','era')}}) is determined by the calendar in use.  The default value of any omitted time-related property (e.g., {{jsxref('Temporal.PlainDateTime/minute','minute')}}) is zero.</p>
-<p>Any non-object, non-string value will be converted to a string, which is expected to be in ISO 8601 format. For other calendars, the calendar is also parsed in addition to date and time. Any other parts of the string, such as a time or time zone, are optional and will be ignored.  If the string is invalid according to ISO 8601, then a <code>RangeError</code> will be thrown regardless of the value of the <code>overflow</code> option (see next).</p>
+<p>Any non-object, non-string value will be converted to a string, which is expected to be in ISO 8601 format. For other calendars, the calendar is also parsed in addition to date and time. Any other parts of the string, such as a time zone, are optional and will be ignored.  If the string is invalid according to ISO 8601, then a <code>RangeError</code> will be thrown regardless of the value of the <code>overflow</code> option (see next).</p>
 </dd>
 <dt><code><var>options</var></code> {{optional_inline}}</dt>
 <dd>

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

@@ -19,7 +19,7 @@
 <h2 id="syntax">Syntax</h2>
 
 <pre class="brush: js">
-var newTime = oldDateTime.round(<var>options</var>);
+var newDateTime = oldDateTime.round(<var>options</var>);
 </pre>
 
 <h3 id="parameters">Parameters</h3>

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

@@ -15,7 +15,7 @@
 <h2 id="syntax">Syntax</h2>
 
 <pre class="brush: js">
-var newDate = dateTime.with(<var>newValues</var>, <var>options</var>);
+var newDateTime = dateTime.with(<var>newValues</var>, <var>options</var>);
 </pre>
 
 <h3 id="parameters">Parameters</h3>
@@ -52,5 +52,5 @@ <h2 id="examples">Examples</h2>
 
 <pre class="brush: js">
 dateTime = Temporal.PlainDateTime.from('1995-12-07T03:24:30.000003500');
-dateTime.with({ year: 2015, second: 31 }); // => 2015-12-07T03:24:31.000003
+dateTime.with({ year: 2015, second: 31 }); // => 2015-12-07T03:24:31.0000035
 </pre>

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

@@ -16,7 +16,7 @@
 <h2 id="syntax">Syntax</h2>
 
 <pre class="brush: js">
-var dateCalendar = date.calendar;
+var calendar = monthDay.calendar;
 </pre>
 
 

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

@@ -20,7 +20,7 @@
 <h2 id="syntax">Syntax</h2>
 
 <pre class="brush: js">
-new Temporal.PlainMonthDay(<var>isoMonth</var>, <var>isoDay</var>, <var>calendar</var>, <var>referenceISOYear</var>)
+new Temporal.PlainMonthDay(<var>isoMonth</var>, <var>isoDay</var>[, <var>calendar</var>, <var>referenceISOYear</var>])
 </pre>
 
 <h3 id="parameters">Parameters</h3>
@@ -41,14 +41,14 @@ <h3 id="parameters">Parameters</h3>
 <dd>
 <p>A calendar to project the ISO 8601 date into, in order to reckon the date by that calendar’s date system.</p>
 <div class="notecard note">
-<p><strong>Note:</strong> if this parameter is anything other than the default value of <code>iso8601</code>, the <var>referenceISOYear</var> parameter is <strong>required</strong>, not optional.</p>
+<p><strong>Note:</strong> if this parameter is anything other than the ISO 8601 calendar (which is the default), it is <strong>recommended</strong> to include the <var>referenceISOYear</var> parameter.</p>
 </div>
 </dd>
 <dt><code><var>referenceISOYear</var></code> {{ optional_inline }}(see note)</dt>
 <dd>
-<p>A reference year in the ISO 8601 calendar, to be used for disambiguation.  If this parameter is not supplied, the default value is the first leap year after the Unix epoch (i.e., 1972 in the ISO 8601 calendar).  Therefore, if you want to construct a PlainMonthDay object for any other ISO 8601 year, use this parameter.</p>
+<p>A reference year in the ISO 8601 calendar, to be used for disambiguation.  If this parameter is not supplied, the default value is the first leap year after the Unix epoch (i.e., 1972).</p>
 <div class="notecard note">
-<p><strong>Note:</strong> this parameter is optional when using the ISO 8601 calendar, but required for all other calendar systems.  If you’re not sure what value to supply here, use <code>{{jsxref('Temporal/PlainMonthDay/from','Temporal.PlainMonthDay.from()')}}</code> instead.</p>
+<p><strong>Note:</strong> this parameter is optional when using the ISO 8601 calendar, but recommended for all other calendar systems.  If you’re not sure what value to supply here, use <code>{{jsxref('Temporal/PlainMonthDay/from','Temporal.PlainMonthDay.from()')}}</code> instead.</p>
 </div>
 </dd>
 </dl>
@@ -72,4 +72,5 @@ <h2 id="examples">Examples</h2>
 // Leap day error
 md = new Temporal.PlainMonthDay(2, 29, 'iso8601', 2021);
   // => Uncaught RangeError: value out of range: 1 <= 29 <= 28
+  // TK not sure we should include this last example, since it's something people should not generally do and don't need to know
 </pre>

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

@@ -16,7 +16,7 @@
 <h2 id="syntax">Syntax</h2>
 
 <pre class="brush: js">
-var dateDay = date.day;
+var day = monthDay.day;
 </pre>
 
 

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

@@ -27,7 +27,7 @@ <h3 id="parameters">Parameters</h3>
 
 <dl>
 <dt><code><var>otherDate</var></code></dt>
-<dd>An object representing the date to which the original date is compared.  If <var>otherdate</var> is not a <code>{{jsxref('Temporal.PlainMonthDay','Temporal.PlainMonthDay')}}</code> object, it is converted to one as if it were passed to <code>{{jsxref('Temporal/PlainMonthDay/from','Temporal.PlainMonthDay.from()')}}</code>.
+<dd>An object representing the date to which the original date is compared.  If <var>otherDate</var> is not a <code>{{jsxref('Temporal.PlainMonthDay','Temporal.PlainMonthDay')}}</code> object, it is converted to one as if it were passed to <code>{{jsxref('Temporal/PlainMonthDay/from','Temporal.PlainMonthDay.from()')}}</code>.
 </dd>
 </dl>
 
@@ -44,4 +44,3 @@ <h2 id="examples">Examples</h2>
 md1.equals(md2); // => false (differing calendars)
 md1.equals(md3); // => false (same calendar, different day)
 </pre>
-

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

@@ -20,7 +20,7 @@
 <h2 id="syntax">Syntax</h2>
 
 <pre class="brush: js">
-var newDate = Temporal.PlainMonthDay.with(<var>newValues</var>, <var>options</var>);
+var newDate = oldDate.with(<var>newValues</var>, <var>options</var>);
 </pre>
 
 <h3 id="parameters">Parameters</h3>
@@ -59,7 +59,6 @@ <h2 id="examples">Examples</h2>
 </pre>
 <pre class="brush: js">
 md = Temporal.PlainMonthDay.from('01-31');
-// Postpone that by three months
+// Equivalent date but in April
 md.with({ monthCode: 'M04' }); // => 04-30
 </pre>
-

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

@@ -19,15 +19,15 @@
 <h2 id="syntax">Syntax</h2>
 
 <pre class="brush: js">
-var newMonth = PlainYearMonth.add(<var>duration</var>, <var>options</var>);
+var newMonth = oldMonth.add(<var>duration</var>, <var>options</var>);
 </pre>
 
 <h3 id="parameters">Parameters</h3>
 
 <dl>
 <dt><code><var>duration</var></code></dt>
 <dd>
-<p>An object with properties denoting a duration, such as <code>{ hours: 5, minutes: 30 }</code>, or a string value such as <code>PT5H30M</code>, or a <code>{{jsxref('Temporal/Duration','Temporal.Duration')}}</code> object. If <code><var>duration</var></code> is not such a string nor a <code>{{jsxref('Temporal/Duration','Temporal.Duration')}}</code> object, then it will be converted to one as if it were passed to <code>{{jsxref('Temporal/Duration/from','Temporal.Duration.from()')}}</code>.</p>
+<p>An object with properties denoting a duration, such as <code>{ months: 5 }</code>, or a string value such as <code>P5M</code>, or a <code>{{jsxref('Temporal/Duration','Temporal.Duration')}}</code> object. If <code><var>duration</var></code> is not such a string nor a <code>{{jsxref('Temporal/Duration','Temporal.Duration')}}</code> object, then it will be converted to one as if it were passed to <code>{{jsxref('Temporal/Duration/from','Temporal.Duration.from()')}}</code>.</p>
 </dd>
 <dt><code><var>options</var></code> {{optional_inline}}</dt>
 <dd>
@@ -50,7 +50,7 @@ <h3 id="parameters">Parameters</h3>
 
 <h2 id="return-value">Return value</h2>
 
-<p>A new <code>{{jsxref('Temporal/PlainYearMonth','Temporal.PlainYearMonth')}}</code> object representing the month indicated by <code>PlainYearMonth</code> plus <code><var>duration</var></code>. If the result is earlier or later than the range that <code>{{jsxref('Temporal/PlainYearMonth','Temporal.PlainYearMonth')}}</code> can represent (just over half a million years centered on the Unix epoch), a <code>RangeError</code> will be thrown instead.
+<p>A new <code>{{jsxref('Temporal/PlainYearMonth','Temporal.PlainYearMonth')}}</code> object representing the month indicated by <code>oldMonth</code> plus <code><var>duration</var></code>. If the result is earlier or later than the range that <code>{{jsxref('Temporal/PlainYearMonth','Temporal.PlainYearMonth')}}</code> can represent (just over half a million years centered on the Unix epoch), a <code>RangeError</code> will be thrown instead.
 </p>
 
 <h2 id="examples">Examples</h2>

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

@@ -15,21 +15,21 @@
 <h2 id="syntax">Syntax</h2>
 
 <pre class="brush: js">
-var dateCalendar = date.calendar;
+var calendar = yearMonth.calendar;
 </pre>
 
 
 <h2 id="value">Value</h2>
 
-<p>A <code>{{jsxref('Temporal/Calendar','Temporal.Calendar')}}</code> object representing the calendar system used to determine the month and day.</p>
+<p>A <code>{{jsxref('Temporal/Calendar','Temporal.Calendar')}}</code> object representing the calendar system used to determine the month and year.</p>
 
 
 <h2 id="examples">Examples</h2>
 
 <pre class="brush: js">
-md = Temporal.PlainYearMonth.from('08-24');
-md.calendar; // returns a Temporal.Calendar object of the ISO 8601 calendar
+ym = Temporal.PlainYearMonth.from('08-24');
+ym.calendar; // returns a Temporal.Calendar object of the ISO 8601 calendar
 
-md = Temporal.PlainYearMonth.from('2019-02-20[u-ca=hebrew]');
-md.calendar; // returns a Temporal.Calendar object of the Hebrew calendar
+ym = Temporal.PlainYearMonth.from('2019-02-20[u-ca=hebrew]');
+ym.calendar; // returns a Temporal.Calendar object of the Hebrew calendar
 </pre>

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

@@ -13,8 +13,8 @@
 ---
 {{JSRef}}
 
-<p class="summary"><span class="seoSummary">The <strong><code>compare()</code></strong> static method compares two dates 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/PlainYearMonth/equals','Temporal.PlainYearMonth.equals()')}}</code> instead.</p>
+<p class="summary"><span class="seoSummary">The <strong><code>compare()</code></strong> static method compares two months 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 months occur, but instead merely want to know if they’re the same or not, use <code>{{jsxref('Temporal/PlainYearMonth/equals','Temporal.PlainYearMonth.equals()')}}</code> instead.</p>
 
 
 <h2 id="syntax">Syntax</h2>

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

@@ -20,7 +20,7 @@
 <h2 id="syntax">Syntax</h2>
 
 <pre class="brush: js">
-new Temporal.PlainYearMonth(<var>isoYear</var>, <var>isoMonth</var>, <var>calendar</var>, <var>referenceISODay</var>)
+new Temporal.PlainYearMonth(<var>isoYear</var>, <var>isoMonth</var>[, <var>calendar</var>, <var>referenceISODay</var>])
 </pre>
 
 <h3 id="parameters">Parameters</h3>
@@ -41,7 +41,7 @@ <h3 id="parameters">Parameters</h3>
 <dd>
 <p>A calendar to project the ISO 8601 date into, in order to reckon the date by that calendar’s date system.</p>
 <div class="notecard note">
-<p><strong>Note:</strong> if this parameter is anything other than the default value of <code>iso8601</code>, the <var>referenceISODay</var> parameter is <strong>required</strong>, not optional.</p>
+<p><strong>Note:</strong> if this parameter is anything other than the default value of the ISO 8601 calendar, it is also <strong>recommended</strong> to include the <var>referenceISODay</var> parameter.</p>
 </div>
 </dd>
 <dt><code><var>referenceISODay</var></code> {{ optional_inline }}(see note)</dt>
@@ -55,7 +55,7 @@ <h3 id="parameters">Parameters</h3>
 
 <h2 id="return-value">Return value</h2>
 
-<p>A new <code>{{jsxref('Temporal/PlainYearMonth','Temporal.PlainYearMonth')}}</code> object.  All values are given as reckoned in the ISO 8601 calendar.  If <var>isoYear</var> or <var>isoMonth</var> are outside of the range of allowed values, then a <code>RangeError</code> in thrownn.</p>
+<p>A new <code>{{jsxref('Temporal/PlainYearMonth','Temporal.PlainYearMonth')}}</code> object.  All values are given as reckoned in the ISO 8601 calendar.  If <var>isoYear</var> or <var>isoMonth</var> are outside of the range of allowed values, then a <code>RangeError</code> is thrown.</p>
 
 <h2 id="examples">Examples</h2>
 

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

@@ -19,7 +19,7 @@
 <h2 id="syntax">Syntax</h2>
 
 <pre class="brush: js">
-var isSameMonth = PlainYearMonth.equals(<var>other</var>);
+var isSameMonth = plainYearMonth.equals(<var>other</var>);
 </pre>
 
 <h3 id="parameters">Parameters</h3>

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

@@ -9,13 +9,13 @@
 ---
 {{JSRef}}
 
-<p class="summary"><span class="seoSummary">The <strong><code>era</code></strong> read-only property returns a string of the era in which the date occurs, in calendar systems that use eras.</span></p>
+<p class="summary"><span class="seoSummary">The <strong><code>era</code></strong> read-only property returns a string of the era in which the month occurs, in calendar systems that use eras.</span></p>
 
 
 <h2 id="syntax">Syntax</h2>
 
 <pre class="brush: js">
-var dateEra = date.era;
+var era = yearMonth.era;
 </pre>
 
 

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

@@ -9,14 +9,14 @@
 ---
 {{JSRef}}
 
-<p class="summary"><span class="seoSummary">The <strong><code>month</code></strong> read-only property returns a number that identifies the month in which the date occurs.</span></p>
+<p class="summary"><span class="seoSummary">The <strong><code>month</code></strong> read-only property returns a number that identifies the month of the year in with the PlainYearMonth occurs.</span></p>
 
 
 
 <h2 id="syntax">Syntax</h2>
 
 <pre class="brush: js">
-var dateMonth = date.month;
+var month = yearMonth.month;
 </pre>
 
 

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

@@ -13,13 +13,13 @@
 ---
 {{JSRef}}
 
-<p class="summary"><span class="seoSummary">The <strong><code>since()</code></strong> method computes the elapsed time from the month represented by <code>PlainYearMonth</code> until the another month, optionally rounds it, and returns it as a <code>{{jsxref('Temporal/Duration','Temporal.Duration')}}</code> object.</span>  If the second month is later than the first, then the resulting duration will be negative.  This method is similar to <code>{{jsxref('Temporal.PlainYearMonth/until','Temporal.PlainYearMonth.until()')}}</code>, but reversed.</p>
+<p class="summary"><span class="seoSummary">The <strong><code>since()</code></strong> method computes the elapsed time from the month represented by <code>yearMonth</code> until another month, optionally rounds it, and returns it as a <code>{{jsxref('Temporal/Duration','Temporal.Duration')}}</code> object.</span>  If the second month is later than the first, then the resulting duration will be negative.  This method is similar to <code>{{jsxref('Temporal.PlainYearMonth/until','Temporal.PlainYearMonth.until()')}}</code>, but reversed.</p>
 
 
 <h2 id="syntax">Syntax</h2>
 
 <pre class="brush: js">
-var timeBetween = PlainYearMonth.since(<var>otherYearMonth</code> [, <var>options</var>])
+var timeBetween = yearMonth.since(<var>otherYearMonth</code> [, <var>options</var>])
 </pre>
 
 <h3 id="parameters">Parameters</h3>

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

@@ -19,15 +19,15 @@
 <h2 id="syntax">Syntax</h2>
 
 <pre class="brush: js">
-var newMonth = PlainYearMonth.subtract(<var>duration</var>, <var>options</var>);
+var newMonth = oldMonth.subtract(<var>duration</var>, <var>options</var>);
 </pre>
 
 <h3 id="parameters">Parameters</h3>
 
 <dl>
 <dt><code><var>duration</var></code></dt>
 <dd>
-<p>An object with properties denoting a duration, such as <code>{ hours: 5, minutes: 30 }</code>, or a string value such as <code>PT5H30M</code>, or a <code>{{jsxref('Temporal/Duration','Temporal.Duration')}}</code> object. If <code><var>duration</var></code> is not such a string nor a <code>{{jsxref('Temporal/Duration','Temporal.Duration')}}</code> object, then it will be converted to one as if it were passed to <code>{{jsxref('Temporal/Duration/from','Temporal.Duration.from()')}}</code>.</p>
+<p>An object with properties denoting a duration, such as <code>{ months: 5 }</code>, or a string value such as <code>P5M</code>, or a <code>{{jsxref('Temporal/Duration','Temporal.Duration')}}</code> object. If <code><var>duration</var></code> is not such a string nor a <code>{{jsxref('Temporal/Duration','Temporal.Duration')}}</code> object, then it will be converted to one as if it were passed to <code>{{jsxref('Temporal/Duration/from','Temporal.Duration.from()')}}</code>.</p>
 </dd>
 <dt><code><var>options</var></code> {{optional_inline}}</dt>
 <dd>
@@ -50,7 +50,7 @@ <h3 id="parameters">Parameters</h3>
 
 <h2 id="return-value">Return value</h2>
 
-<p>A new <code>{{jsxref('Temporal/PlainYearMonth','Temporal.PlainYearMonth')}}</code> object representing the year and month indicated by the original <code>PlainYearMonth</code> minus <code><var>duration</var></code>. If the result is earlier or later than the range that <code>{{jsxref('Temporal/PlainYearMonth','Temporal.PlainYearMonth')}}</code> can represent (just over half a million years centered on the Unix epoch), a <code>RangeError</code> will be thrown instead.
+<p>A new <code>{{jsxref('Temporal/PlainYearMonth','Temporal.PlainYearMonth')}}</code> object representing the year and month indicated by the original <code>oldMonth</code> minus <code><var>duration</var></code>. If the result is earlier or later than the range that <code>{{jsxref('Temporal/PlainYearMonth','Temporal.PlainYearMonth')}}</code> can represent (just over half a million years centered on the Unix epoch), a <code>RangeError</code> will be thrown instead.
 </p>
 
 <h2 id="examples">Examples</h2>