Last group of reviews

files/en-us/web/javascript/reference/global_objects/temporal/duration/compare/index.md

@@ -35,7 +35,6 @@ Returns `-1` if `duration1` is shorter than `duration2`, `0` if they are equal,
 
 - {{jsxref("RangeError")}}
   - : Thrown if either `duration1` or `duration2` is a [calendar duration](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration#calendar_durations) (it has a non-zero `years`, `months`, or `weeks`), and `relativeTo` is not provided.
-    - Either `duration1` or `duration2` is a calendar duration, and `relativeTo` is not provided.
 
 ## Description
 

files/en-us/web/javascript/reference/global_objects/temporal/duration/days/index.md

@@ -34,6 +34,7 @@ const d4Balanced = d4.round({
   relativeTo: Temporal.PlainDate.from("2021-01-01"), // ISO 8601 calendar
 });
 console.log(d4Balanced.days); // 0
+console.log(d4Balanced.weeks); // 1
 ```
 
 ## Specifications

files/en-us/web/javascript/reference/global_objects/temporal/duration/hours/index.md

@@ -31,6 +31,7 @@ console.log(d4.hours); // 24
 // Balance d4
 const d4Balanced = d4.round({ largestUnit: "day" });
 console.log(d4Balanced.hours); // 0
+console.log(d4Balanced.days); // 1
 ```
 
 ## Specifications

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

@@ -50,7 +50,7 @@ When serializing, the output respects the stored components as much as possible,
 
 ### Calendar durations
 
-A _calendar duration_ is one that contains any of the [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars) units: weeks, months, and years. A non-calendar duration is portable and can participate in date/time arithmetic without any calendar information, because they unambiguously represent a fixed amount of time. However, a calendar duration is not portable because the number of days in a month or year depends on the calendar system and the reference time point. Therefore, attempting to perform any arithmetic operation on a calendar durations throws an error because durations don't keep track of a calendar themselves. For example, if we are in May of the Gregorian calendar, then "1 month" is "31 days", but if we are in April, then "1 month" becomes "30 days". To add or subtract calendar durations, you need to add them to dates instead (which, by nature of date calculations, returns you a non-calendar duration):
+A _calendar duration_ is one that contains any of the [calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars) units: weeks, months, and years. A non-calendar duration is portable and can participate in date/time arithmetic without any calendar information, because they unambiguously represent a fixed amount of time. However, a calendar duration is not portable because the number of days in a month or year depends on the calendar system and the reference time point. Therefore, attempting to perform any arithmetic operation on a calendar durations throws an error because durations don't keep track of a calendar themselves. For example, if we are in May of the Gregorian calendar, then "1 month" is "31 days", but if we are in April, then "1 month" becomes "30 days". To add or subtract calendar durations, you need to add them to dates instead:
 
 ```js
 const dur1 = Temporal.Duration.from({ years: 1 });

files/en-us/web/javascript/reference/global_objects/temporal/duration/microseconds/index.md

@@ -31,6 +31,7 @@ console.log(d4.microseconds); // 1000
 // Balance d4
 const d4Balanced = d4.round({ largestUnit: "millisecond" });
 console.log(d4Balanced.microseconds); // 0
+console.log(d4Balanced.milliseconds); // 1
 ```
 
 ## Specifications

files/en-us/web/javascript/reference/global_objects/temporal/duration/milliseconds/index.md

@@ -31,6 +31,7 @@ console.log(d4.milliseconds); // 1000
 // Balance d4
 const d4Balanced = d4.round({ largestUnit: "second" });
 console.log(d4Balanced.milliseconds); // 0
+console.log(d4Balanced.seconds); // 1
 ```
 
 ## Specifications

files/en-us/web/javascript/reference/global_objects/temporal/duration/minutes/index.md

@@ -31,6 +31,7 @@ console.log(d4.minutes); // 60
 // Balance d4
 const d4Balanced = d4.round({ largestUnit: "hour" });
 console.log(d4Balanced.minutes); // 0
+console.log(d4Balanced.hours); // 1
 ```
 
 ## Specifications

files/en-us/web/javascript/reference/global_objects/temporal/duration/months/index.md

@@ -34,6 +34,7 @@ const d4Balanced = d4.round({
   relativeTo: Temporal.PlainDate.from("2021-01-01"), // ISO 8601 calendar
 });
 console.log(d4Balanced.months); // 0
+console.log(d4Balanced.years); // 1
 ```
 
 ## Specifications

files/en-us/web/javascript/reference/global_objects/temporal/duration/nanoseconds/index.md

@@ -31,6 +31,7 @@ console.log(d4.nanoseconds); // 1000
 // Balance d4
 const d4Balanced = d4.round({ largestUnit: "microsecond" });
 console.log(d4Balanced.nanoseconds); // 0
+console.log(d4Balanced.microseconds); // 1
 ```
 
 ## Specifications

files/en-us/web/javascript/reference/global_objects/temporal/duration/seconds/index.md

@@ -31,6 +31,7 @@ console.log(d4.seconds); // 60
 // Balance d4
 const d4Balanced = d4.round({ largestUnit: "minute" });
 console.log(d4Balanced.seconds); // 0
+console.log(d4Balanced.minutes); // 1
 ```
 
 ## Specifications

files/en-us/web/javascript/reference/global_objects/temporal/duration/valueof/index.md

@@ -32,6 +32,24 @@ None.
 
 Because both [primitive conversion](/en-US/docs/Web/JavaScript/Data_structures#primitive_coercion) and [number conversion](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_coercion) call `valueOf()` before `toString()`, if `valueOf()` is absent, then an expression like `duration1 > duration2` would implicitly compare them as strings, which may have unexpected results such as `"PT3S" > "PT1M"`. By throwing a `TypeError`, `Temporal.Duration` instances prevent such implicit conversions. You need to explicitly convert them to numbers using {{jsxref("Temporal/Duration/total", "Temporal.Duration.prototype.total()")}}, or use the {{jsxref("Temporal/Duration/compare", "Temporal.Duration.compare()")}} static method to compare them.
 
+## Examples
+
+### Arithmetic and comparison operations on Temporal.Duration
+
+All arithmetic and comparison operations on `Temporal.Duration` instances should use the dedicated methods or convert them to primitives explicitly.
+
+```js
+const duration1 = Temporal.Duration.from({ seconds: 3 });
+const duration2 = Temporal.Duration.from({ minutes: 1 });
+duration1 > duration2; // TypeError: can't convert Duration to primitive type
+duration1.total("seconds") > duration2.total("seconds"); // false
+Temporal.Duration.compare(duration1, duration2); // -1
+
+duration1 + duration2; // TypeError: can't convert Duration to primitive type
+duration1.total("seconds") + duration2.total("seconds"); // 63
+duration1.add(duration2).toString(); // "PT1M3S"
+```
+
 ## Specifications
 
 {{Specifications}}

files/en-us/web/javascript/reference/global_objects/temporal/duration/weeks/index.md

@@ -34,6 +34,7 @@ const d4Balanced = d4.round({
   relativeTo: Temporal.PlainDate.from("2021-01-01"), // ISO 8601 calendar
 });
 console.log(d4Balanced.weeks); // 1
+console.log(d4Balanced.days); // 0
 ```
 
 ## Specifications

files/en-us/web/javascript/reference/global_objects/temporal/duration/years/index.md

@@ -25,15 +25,16 @@ const d4 = Temporal.Duration.from({ months: 12 });
 
 console.log(d1.years); // 1
 console.log(d2.years); // -1
-console.log(d3.years); // 0
-console.log(d4.years); // 12
+console.log(d3.years); // 1
+console.log(d4.years); // 0
 
 // Balance d4
 const d4Balanced = d4.round({
   largestUnit: "year",
   relativeTo: Temporal.PlainDate.from("2021-01-01"), // ISO 8601 calendar
 });
 console.log(d4Balanced.years); // 1
+console.log(d4Balanced.months); // 0
 ```
 
 ## Specifications

files/en-us/web/javascript/reference/global_objects/temporal/instant/valueof/index.md

@@ -32,6 +32,23 @@ None.
 
 Because both [primitive conversion](/en-US/docs/Web/JavaScript/Data_structures#primitive_coercion) and [number conversion](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_coercion) call `valueOf()` before `toString()`, if `valueOf()` is absent, then an expression like `instant1 > instant2` would implicitly compare them as strings, which may have unexpected results. By throwing a `TypeError`, `Temporal.Instant` instances prevent such implicit conversions. You need to explicitly convert them to numbers using {{jsxref("Temporal/Instant/epochNanoseconds", "Temporal.Instant.prototype.epochNanoseconds")}}, or use the {{jsxref("Temporal/Instant/compare", "Temporal.Instant.compare()")}} static method to compare them.
 
+## Examples
+
+### Arithmetic and comparison operations on Temporal.Instant
+
+All arithmetic and comparison operations on `Temporal.Instant` instances should use the dedicated methods or convert them to primitives explicitly.
+
+```js
+const instant1 = Temporal.Instant.fromEpochMilliseconds(0);
+const instant2 = Temporal.Instant.fromEpochMilliseconds(1000);
+instant1 > instant2; // TypeError: can't convert Instant to primitive type
+instant1.epochNanoseconds > instant2.epochNanoseconds; // false
+Temporal.Instant.compare(instant1, instant2); // -1
+
+instant2 - instant1; // TypeError: can't convert Instant to primitive type
+instant2.since(instant1).toString(); // "PT1S"
+```
+
 ## Specifications
 
 {{Specifications}}

files/en-us/web/javascript/reference/global_objects/temporal/plaindate/valueof/index.md

@@ -32,6 +32,22 @@ None.
 
 Because both [primitive conversion](/en-US/docs/Web/JavaScript/Data_structures#primitive_coercion) and [number conversion](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_coercion) call `valueOf()` before `toString()`, if `valueOf()` is absent, then an expression like `date1 > date2` would implicitly compare them as strings, which may have unexpected results. By throwing a `TypeError`, `Temporal.PlainDate` instances prevent such implicit conversions. You need to explicitly convert them to strings using {{jsxref("Temporal/PlainDate/toString", "Temporal.PlainDate.prototype.toString()")}}, or use the {{jsxref("Temporal/PlainDate/compare", "Temporal.PlainDate.compare()")}} static method to compare them.
 
+## Examples
+
+### Arithmetic and comparison operations on Temporal.PlainDate
+
+All arithmetic and comparison operations on `Temporal.PlainDate` instances should use the dedicated methods or convert them to primitives explicitly.
+
+```js
+const date1 = Temporal.PlainDate.from("2022-01-01");
+const date2 = Temporal.PlainDate.from("2022-07-01");
+date1 > date2; // TypeError: can't convert PlainDate to primitive type
+Temporal.PlainDate.compare(date1, date2); // -1
+
+date2 - date1; // TypeError: can't convert PlainDate to primitive type
+date2.since(date1).toString(); // "P181D"
+```
+
 ## Specifications
 
 {{Specifications}}

files/en-us/web/javascript/reference/global_objects/temporal/plaindatetime/valueof/index.md

@@ -32,6 +32,22 @@ None.
 
 Because both [primitive conversion](/en-US/docs/Web/JavaScript/Data_structures#primitive_coercion) and [number conversion](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_coercion) call `valueOf()` before `toString()`, if `valueOf()` is absent, then an expression like `dateTime1 > dateTime2` would implicitly compare them as strings, which may have unexpected results. By throwing a `TypeError`, `Temporal.PlainDateTime` instances prevent such implicit conversions. You need to explicitly convert them to strings using {{jsxref("Temporal/PlainDateTime/toString", "Temporal.PlainDateTime.prototype.toString()")}}, or use the {{jsxref("Temporal/PlainDateTime/compare", "Temporal.PlainDateTime.compare()")}} static method to compare them.
 
+## Examples
+
+### Arithmetic and comparison operations on Temporal.PlainDateTime
+
+All arithmetic and comparison operations on `Temporal.PlainDateTime` instances should use the dedicated methods or convert them to primitives explicitly.
+
+```js
+const dt1 = Temporal.PlainDateTime.from("2022-01-01T00:00:00");
+const dt2 = Temporal.PlainDateTime.from("2022-07-01T00:00:00");
+dt1 > dt2; // TypeError: can't convert PlainDateTime to primitive type
+Temporal.PlainDateTime.compare(dt1, dt2); // -1
+
+dt2 - dt1; // TypeError: can't convert PlainDateTime to primitive type
+dt2.since(dt1).toString(); // "P181D"
+```
+
 ## Specifications
 
 {{Specifications}}

files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/from/index.md

@@ -39,8 +39,6 @@ Temporal.PlainMonthDay.from(info, options)
       - `year`
         - : An integer used to disambiguate `month` if provided, because for some calendars, the same `month` can mean different `monthCode` in different years. See {{jsxref("Temporal/PlainDate/year", "year")}} of `PlainDate`. If a year is provided, then the `overflow` option validates the month-day in the given year, not just any year. If `month` is specified, at least one of `era`+`eraYear` or `year` must be provided. If all of `era`, `eraYear`, and `year` are provided, they must be consistent.
 
-      Other `Temporal` objects, such as {{jsxref("Temporal.PlainDate")}}, {{jsxref("Temporal.PlainDateTime")}} and {{jsxref("Temporal.ZonedDateTime")}}, conform to this shape and can be used as well.
-
 - `options` {{optional_inline}}
   - : An object containing the following property:
     - `overflow` {{optional_inline}}

files/en-us/web/javascript/reference/global_objects/temporal/plainmonthday/valueof/index.md

@@ -32,6 +32,28 @@ None.
 
 Because both [primitive conversion](/en-US/docs/Web/JavaScript/Data_structures#primitive_coercion) and [number conversion](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_coercion) call `valueOf()` before `toString()`, if `valueOf()` is absent, then an expression like `monthDay1 > monthDay2` would implicitly compare them as strings, which may have unexpected results. By throwing a `TypeError`, `Temporal.PlainMonthDay` instances prevent such implicit conversions. You need to explicitly convert them to strings using {{jsxref("Temporal/PlainMonthDay/toString", "Temporal.PlainMonthDay.prototype.toString()")}}.
 
+## Examples
+
+### Arithmetic and comparison operations on Temporal.PlainMonthDay
+
+All arithmetic and comparison operations on `Temporal.PlainMonthDay` instances should use the dedicated methods or convert them to primitives explicitly.
+
+```js
+const md1 = Temporal.PlainMonthDay.from("01-01");
+const md2 = Temporal.PlainMonthDay.from("07-01");
+md1 > md2; // TypeError: can't convert PlainMonthDay to primitive type
+Temporal.PlainDate.compare(
+  md1.toPlainDate({ year: 2021 }),
+  md2.toPlainDate({ year: 2021 }),
+); // -1
+
+md2 - md1; // TypeError: can't convert PlainMonthDay to primitive type
+md2
+  .toPlainDate({ year: 2021 })
+  .since(md1.toPlainDate({ year: 2021 }))
+  .toString(); // "P181D"
+```
+
 ## Specifications
 
 {{Specifications}}

files/en-us/web/javascript/reference/global_objects/temporal/plaintime/valueof/index.md

@@ -32,6 +32,22 @@ None.
 
 Because both [primitive conversion](/en-US/docs/Web/JavaScript/Data_structures#primitive_coercion) and [number conversion](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_coercion) call `valueOf()` before `toString()`, if `valueOf()` is absent, then an expression like `time1 > time2` would implicitly compare them as strings, which may have unexpected results. By throwing a `TypeError`, `Temporal.PlainTime` instances prevent such implicit conversions. You need to explicitly convert them to strings using {{jsxref("Temporal/PlainTime/toString", "Temporal.PlainTime.prototype.toString()")}}, or use the {{jsxref("Temporal/PlainTime/compare", "Temporal.PlainTime.compare()")}} static method to compare them.
 
+## Examples
+
+### Arithmetic and comparison operations on Temporal.PlainTime
+
+All arithmetic and comparison operations on `Temporal.PlainTime` instances should use the dedicated methods or convert them to primitives explicitly.
+
+```js
+const time1 = Temporal.PlainTime.from("00:00:00");
+const time2 = Temporal.PlainTime.from("12:00:00");
+time1 > time2; // TypeError: can't convert PlainTime to primitive type
+Temporal.PlainTime.compare(time1, time2); // -1
+
+time2 - time1; // TypeError: can't convert PlainTime to primitive type
+time2.since(time1).toString(); // "PT12H"
+```
+
 ## Specifications
 
 {{Specifications}}

files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/tojson/index.md

@@ -33,7 +33,7 @@ The `toJSON()` method is automatically called by {{jsxref("JSON.stringify()")}}
 
 ```js
 const ym = Temporal.PlainYearMonth.from({ year: 2021, month: 8 });
-const ymStr = date.toJSON(); // '2021-08'
+const ymStr = ym.toJSON(); // '2021-08'
 const ym2 = Temporal.PlainYearMonth.from(ymStr);
 ```
 

files/en-us/web/javascript/reference/global_objects/temporal/plainyearmonth/valueof/index.md

@@ -32,6 +32,22 @@ None.
 
 Because both [primitive conversion](/en-US/docs/Web/JavaScript/Data_structures#primitive_coercion) and [number conversion](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_coercion) call `valueOf()` before `toString()`, if `valueOf()` is absent, then an expression like `yearMonth1 > yearMonth2` would implicitly compare them as strings, which may have unexpected results. By throwing a `TypeError`, `Temporal.PlainYearMonth` instances prevent such implicit conversions. You need to explicitly convert them to strings using {{jsxref("Temporal/PlainYearMonth/toString", "Temporal.PlainYearMonth.prototype.toString()")}}, or use the {{jsxref("Temporal/PlainYearMonth/compare", "Temporal.PlainYearMonth.compare()")}} static method to compare them.
 
+## Examples
+
+### Arithmetic and comparison operations on Temporal.PlainYearMonth
+
+All arithmetic and comparison operations on `Temporal.PlainYearMonth` instances should use the dedicated methods or convert them to primitives explicitly.
+
+```js
+const ym1 = Temporal.PlainYearMonth.from("2021-01");
+const ym2 = Temporal.PlainYearMonth.from("2021-07");
+ym1 > ym2; // TypeError: can't convert PlainYearMonth to primitive type
+Temporal.PlainYearMonth.compare(ym1, ym2); // -1
+
+ym2 - ym1; // TypeError: can't convert PlainYearMonth to primitive type
+ym2.since(ym1).toString(); // "P6M"
+```
+
 ## Specifications
 
 {{Specifications}}

files/en-us/web/javascript/reference/global_objects/temporal/zoneddatetime/valueof/index.md

@@ -32,6 +32,26 @@ None.
 
 Because both [primitive conversion](/en-US/docs/Web/JavaScript/Data_structures#primitive_coercion) and [number conversion](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_coercion) call `valueOf()` before `toString()`, if `valueOf()` is absent, then an expression like `yearMonth1 > yearMonth2` would implicitly compare them as strings, which may have unexpected results. By throwing a `TypeError`, `Temporal.ZonedDateTime` instances prevent such implicit conversions. You need to explicitly convert them to numbers using {{jsxref("Temporal/ZonedDateTime/epochNanoseconds", "Temporal.ZonedDateTime.prototype.epochNanoseconds")}}, or use the {{jsxref("Temporal/ZonedDateTime/compare", "Temporal.ZonedDateTime.compare()")}} static method to compare them.
 
+## Examples
+
+### Arithmetic and comparison operations on Temporal.ZonedDateTime
+
+All arithmetic and comparison operations on `Temporal.ZonedDateTime` instances should use the dedicated methods or convert them to primitives explicitly.
+
+```js
+const zdt1 = Temporal.ZonedDateTime.from(
+  "2022-01-01T00:00:00[America/New_York]",
+);
+const zdt2 = Temporal.ZonedDateTime.from(
+  "2022-07-01T00:00:00[America/New_York]",
+);
+zdt1 > zdt2; // TypeError: can't convert ZonedDateTime to primitive type
+Temporal.ZonedDateTime.compare(zdt1, zdt2); // -1
+
+zdt2 - zdt1; // TypeError: can't convert ZonedDateTime to primitive type
+zdt2.since(zdt1).toString(); // "PT4343H"
+```
+
 ## Specifications
 
 {{Specifications}}