PlainTime docs

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

@@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.Instant.equals
 
 {{JSRef}}
 
-The **`equals()`** method of {{jsxref("Temporal.Instant")}} instances returns `true` if this instant is equal to another instant (in a form convertible by {{jsxref("Temporal/Instant/from", "Temporal.Instant.from()")}}), and `false` otherwise. Equivalent to `Temporal.Instant.compare(this, other) === 0`.
+The **`equals()`** method of {{jsxref("Temporal.Instant")}} instances returns `true` if this instant is equivalent in value to another instant (in a form convertible by {{jsxref("Temporal/Instant/from", "Temporal.Instant.from()")}}), and `false` otherwise. They are compared by their epoch nanoseconds. Equivalent to `Temporal.Instant.compare(this, other) === 0`.
 
 ## Syntax
 

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

@@ -78,7 +78,7 @@ These properties are defined on `Temporal.Instant.prototype` and shared by all `
 - {{jsxref("Temporal/Instant/add", "Temporal.Instant.prototype.add()")}}
   - : Returns a new `Temporal.Instant` object representing this instant moved forward by a given duration (in a form convertible by {{jsxref("Temporal/Duration/from", "Temporal.Duration.from()")}}).
 - {{jsxref("Temporal/Instant/equals", "Temporal.Instant.prototype.equals()")}}
-  - : Returns `true` if this instant is equal to another instant (in a form convertible by {{jsxref("Temporal/Instant/from", "Temporal.Instant.from()")}}), and `false` otherwise. Equivalent to `Temporal.Instant.compare(this, other) === 0`.
+  - : Returns `true` if this instant is equivalent in value to another instant (in a form convertible by {{jsxref("Temporal/Instant/from", "Temporal.Instant.from()")}}), and `false` otherwise. They are compared by their epoch nanoseconds. Equivalent to `Temporal.Instant.compare(this, other) === 0`.
 - {{jsxref("Temporal/Instant/round", "Temporal.Instant.prototype.round()")}}
   - : Returns a new `Temporal.Instant` object representing this instant rounded to the given unit.
 - {{jsxref("Temporal/Instant/since", "Temporal.Instant.prototype.since()")}}

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

@@ -33,7 +33,7 @@ subtract(duration, options)
 
 ### Return value
 
-A new `Temporal.PlainDate` object representing the date specified by the original date, minus the duration.
+A new `Temporal.PlainDate` object representing the date specified by the original `PlainDate`, minus the duration.
 
 ## Description
 

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

@@ -7,15 +7,20 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.hour
 
 {{JSRef}}
 
-The **`hour`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances TODO
+The **`hour`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances returns a integer from 0 to 23 representing the hour component of this time.
 
-## Description
+The set accessor of `hour` is `undefined`. You cannot change this property directly. Use the {{jsxref("Temporal/PlainDateTime/with", "with()")}} method to create a new `Temporal.PlainDateTime` object with the desired new value.
 
-TODO
+For general information and more examples, see {{jsxref("Temporal/PlainTime/hour", "Temporal.PlainTime.prototype.hour")}}.
 
 ## Examples
 
-TODO
+### Using hour
+
+```js
+const dt = Temporal.PlainDateTime.from("2021-07-01T12:34:56.123456789");
+console.log(dt.hour); // 12
+```
 
 ## Specifications
 
@@ -27,4 +32,8 @@ TODO
 
 ## See also
 
-- TODO
+- {{jsxref("Temporal.PlainDateTime")}}
+- {{jsxref("Temporal/PlainDateTime/with", "Temporal.PlainDateTime.prototype.with()")}}
+- {{jsxref("Temporal/PlainDateTime/add", "Temporal.PlainDateTime.prototype.add()")}}
+- {{jsxref("Temporal/PlainDateTime/subtract", "Temporal.PlainDateTime.prototype.subtract()")}}
+- {{jsxref("Temporal/PlainTime/hour", "Temporal.PlainTime.prototype.hour")}}

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

@@ -79,25 +79,25 @@ These properties are defined on `Temporal.PlainDateTime.prototype` and shared by
 - {{jsxref("Temporal/PlainDateTime/eraYear", "Temporal.PlainDateTime.prototype.eraYear")}}
   - : Returns a non-negative integer representing the year of this date within the era, or `undefined` if the calendar does not use eras (e.g. ISO 8601). The year index usually starts from 1 (more common) or 0, and years in an era can decrease with time (e.g. Gregorian BCE). `era` and `eraYear` together uniquely identify a year in a calendar, in the same way as `year` does. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent.
 - {{jsxref("Temporal/PlainDateTime/hour", "Temporal.PlainDateTime.prototype.hour")}}
-  - : TODO
+  - : Returns a integer from 0 to 23 representing the hour component of this time.
 - {{jsxref("Temporal/PlainDateTime/inLeapYear", "Temporal.PlainDateTime.prototype.inLeapYear")}}
   - : Returns a boolean indicating whether this date is in a leap year. A leap year is a year that has more days (a leap day or leap month) than a common year. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent.
 - {{jsxref("Temporal/PlainDateTime/microsecond", "Temporal.PlainDateTime.prototype.microsecond")}}
-  - : TODO
+  - : Returns a integer from 0 to 999 representing the microsecond (10<sup>-6</sup> second) component of this time.
 - {{jsxref("Temporal/PlainDateTime/millisecond", "Temporal.PlainDateTime.prototype.millisecond")}}
-  - : TODO
+  - : Returns a integer from 0 to 999 representing the millisecond (10<sup>-3</sup> second) component of this time.
 - {{jsxref("Temporal/PlainDateTime/minute", "Temporal.PlainDateTime.prototype.minute")}}
-  - : TODO
+  - : Returns a integer from 0 to 59 representing the minute component of this time.
 - {{jsxref("Temporal/PlainDateTime/month", "Temporal.PlainDateTime.prototype.month")}}
   - : Returns a positive integer representing the 1-based month index in the year of this date. The first month of this year is `1`, and the last month is the {{jsxref("Temporal/PlainDateTime/monthsInYear", "monthsInYear")}}. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent.
 - {{jsxref("Temporal/PlainDateTime/monthCode", "Temporal.PlainDateTime.prototype.monthCode")}}
   - : Returns a calendar-specific string representing the month of this date. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent.
 - {{jsxref("Temporal/PlainDateTime/monthsInYear", "Temporal.PlainDateTime.prototype.monthsInYear")}}
   - : Returns a positive integer representing the number of months in the year of this date. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent.
 - {{jsxref("Temporal/PlainDateTime/nanosecond", "Temporal.PlainDateTime.prototype.nanosecond")}}
-  - : TODO
+  - : Returns a integer from 0 to 999 representing the nanosecond (10<sup>-9</sup> second) component of this time.
 - {{jsxref("Temporal/PlainDateTime/second", "Temporal.PlainDateTime.prototype.second")}}
-  - : TODO
+  - : Returns a integer from 0 to 59 representing the second component of this time.
 - {{jsxref("Temporal/PlainDateTime/weekOfYear", "Temporal.PlainDateTime.prototype.weekOfYear")}}
   - : Returns a positive integer representing the 1-based week index in the {{jsxref("Temporal/PlainDateTime/yearOfWeek", "yearOfWeek")}} of this date, or `undefined` if the calendar does not have a well-defined week system. The first week of the year is `1`. [Calendar](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal#calendars)-dependent.
 - {{jsxref("Temporal/PlainDateTime/year", "Temporal.PlainDateTime.prototype.year")}}

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

@@ -7,15 +7,20 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.microsecond
 
 {{JSRef}}
 
-The **`microsecond`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances TODO
+The **`microsecond`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances returns a integer from 0 to 999 representing the microsecond (10<sup>-6</sup> second) component of this time.
 
-## Description
+The set accessor of `microsecond` is `undefined`. You cannot change this property directly. Use the {{jsxref("Temporal/PlainDateTime/with", "with()")}} method to create a new `Temporal.PlainDateTime` object with the desired new value.
 
-TODO
+For general information and more examples, see {{jsxref("Temporal/PlainTime/microsecond", "Temporal.PlainTime.prototype.microsecond")}}.
 
 ## Examples
 
-TODO
+### Using microsecond
+
+```js
+const dt = Temporal.PlainDateTime.from("2021-07-01T12:34:56.123456789");
+console.log(dt.microsecond); // 456
+```
 
 ## Specifications
 
@@ -27,4 +32,11 @@ TODO
 
 ## See also
 
-- TODO
+- {{jsxref("Temporal.PlainDateTime")}}
+- {{jsxref("Temporal/PlainDateTime/with", "Temporal.PlainDateTime.prototype.with()")}}
+- {{jsxref("Temporal/PlainDateTime/add", "Temporal.PlainDateTime.prototype.add()")}}
+- {{jsxref("Temporal/PlainDateTime/subtract", "Temporal.PlainDateTime.prototype.subtract()")}}
+- {{jsxref("Temporal/PlainDateTime/second", "Temporal.PlainDateTime.prototype.second")}}
+- {{jsxref("Temporal/PlainDateTime/millisecond", "Temporal.PlainDateTime.prototype.millisecond")}}
+- {{jsxref("Temporal/PlainDateTime/nanosecond", "Temporal.PlainDateTime.prototype.nanosecond")}}
+- {{jsxref("Temporal/PlainTime/microsecond", "Temporal.PlainTime.prototype.microsecond")}}

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

@@ -7,15 +7,20 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.millisecond
 
 {{JSRef}}
 
-The **`millisecond`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances TODO
+The **`millisecond`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances returns a integer from 0 to 999 representing the millisecond (10<sup>-3</sup> second) component of this time.
 
-## Description
+The set accessor of `millisecond` is `undefined`. You cannot change this property directly. Use the {{jsxref("Temporal/PlainDateTime/with", "with()")}} method to create a new `Temporal.PlainDateTime` object with the desired new value.
 
-TODO
+For general information and more examples, see {{jsxref("Temporal/PlainTime/millisecond", "Temporal.PlainTime.prototype.millisecond")}}.
 
 ## Examples
 
-TODO
+### Using millisecond
+
+```js
+const dt = Temporal.PlainDateTime.from("2021-07-01T12:34:56.123456789");
+console.log(dt.millisecond); // 123
+```
 
 ## Specifications
 
@@ -27,4 +32,11 @@ TODO
 
 ## See also
 
-- TODO
+- {{jsxref("Temporal.PlainDateTime")}}
+- {{jsxref("Temporal/PlainDateTime/with", "Temporal.PlainDateTime.prototype.with()")}}
+- {{jsxref("Temporal/PlainDateTime/add", "Temporal.PlainDateTime.prototype.add()")}}
+- {{jsxref("Temporal/PlainDateTime/subtract", "Temporal.PlainDateTime.prototype.subtract()")}}
+- {{jsxref("Temporal/PlainDateTime/second", "Temporal.PlainDateTime.prototype.second")}}
+- {{jsxref("Temporal/PlainDateTime/microsecond", "Temporal.PlainDateTime.prototype.microsecond")}}
+- {{jsxref("Temporal/PlainDateTime/nanosecond", "Temporal.PlainDateTime.prototype.nanosecond")}}
+- {{jsxref("Temporal/PlainTime/millisecond", "Temporal.PlainTime.prototype.millisecond")}}

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

@@ -7,15 +7,20 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.minute
 
 {{JSRef}}
 
-The **`minute`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances TODO
+The **`minute`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances returns a integer from 0 to 59 representing the minute component of this time.
 
-## Description
+The set accessor of `minute` is `undefined`. You cannot change this property directly. Use the {{jsxref("Temporal/PlainDateTime/with", "with()")}} method to create a new `Temporal.PlainDateTime` object with the desired new value.
 
-TODO
+For general information and more examples, see {{jsxref("Temporal/PlainTime/minute", "Temporal.PlainTime.prototype.minute")}}.
 
 ## Examples
 
-TODO
+### Using minute
+
+```js
+const dt = Temporal.PlainDateTime.from("2021-07-01T12:34:56.123456789");
+console.log(dt.minute); // 34
+```
 
 ## Specifications
 
@@ -27,4 +32,8 @@ TODO
 
 ## See also
 
-- TODO
+- {{jsxref("Temporal.PlainDateTime")}}
+- {{jsxref("Temporal/PlainDateTime/with", "Temporal.PlainDateTime.prototype.with()")}}
+- {{jsxref("Temporal/PlainDateTime/add", "Temporal.PlainDateTime.prototype.add()")}}
+- {{jsxref("Temporal/PlainDateTime/subtract", "Temporal.PlainDateTime.prototype.subtract()")}}
+- {{jsxref("Temporal/PlainTime/minute", "Temporal.PlainDateTime.prototype.minute")}}

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

@@ -7,15 +7,20 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.nanosecond
 
 {{JSRef}}
 
-The **`nanosecond`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances TODO
+The **`nanosecond`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances returns a integer from 0 to 999 representing the nanosecond (10<sup>-9</sup> second) component of this time.
 
-## Description
+The set accessor of `nanosecond` is `undefined`. You cannot change this property directly. Use the {{jsxref("Temporal/PlainDateTime/with", "with()")}} method to create a new `Temporal.PlainDateTime` object with the desired new value.
 
-TODO
+For general information and more examples, see {{jsxref("Temporal/PlainTime/nanosecond", "Temporal.PlainTime.prototype.nanosecond")}}.
 
 ## Examples
 
-TODO
+### Using nanosecond
+
+```js
+const dt = Temporal.PlainDateTime.from("2021-07-01T12:34:56.123456789");
+console.log(dt.nanosecond); // 789
+```
 
 ## Specifications
 
@@ -27,4 +32,11 @@ TODO
 
 ## See also
 
-- TODO
+- {{jsxref("Temporal.PlainDateTime")}}
+- {{jsxref("Temporal/PlainDateTime/with", "Temporal.PlainDateTime.prototype.with()")}}
+- {{jsxref("Temporal/PlainDateTime/add", "Temporal.PlainDateTime.prototype.add()")}}
+- {{jsxref("Temporal/PlainDateTime/subtract", "Temporal.PlainDateTime.prototype.subtract()")}}
+- {{jsxref("Temporal/PlainDateTime/second", "Temporal.PlainDateTime.prototype.second")}}
+- {{jsxref("Temporal/PlainDateTime/millisecond", "Temporal.PlainDateTime.prototype.millisecond")}}
+- {{jsxref("Temporal/PlainDateTime/microsecond", "Temporal.PlainDateTime.prototype.microsecond")}}
+- {{jsxref("Temporal/PlainTime/nanosecond", "Temporal.PlainTime.prototype.nanosecond")}}

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

@@ -7,15 +7,20 @@ browser-compat: javascript.builtins.Temporal.PlainDateTime.second
 
 {{JSRef}}
 
-The **`second`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances TODO
+The **`second`** accessor property of {{jsxref("Temporal.PlainDateTime")}} instances returns a integer from 0 to 59 representing the second component of this time.
 
-## Description
+The set accessor of `second` is `undefined`. You cannot change this property directly. Use the {{jsxref("Temporal/PlainDateTime/with", "with()")}} method to create a new `Temporal.PlainDateTime` object with the desired new value.
 
-TODO
+For general information and more examples, see {{jsxref("Temporal/PlainTime/second", "Temporal.PlainTime.prototype.second")}}.
 
 ## Examples
 
-TODO
+### Using second
+
+```js
+const dt = Temporal.PlainDateTime.from("2021-07-01T12:34:56.123456789");
+console.log(dt.second); // 56
+```
 
 ## Specifications
 
@@ -27,4 +32,11 @@ TODO
 
 ## See also
 
-- TODO
+- {{jsxref("Temporal.PlainDateTime")}}
+- {{jsxref("Temporal/PlainDateTime/with", "Temporal.PlainDateTime.prototype.with()")}}
+- {{jsxref("Temporal/PlainDateTime/add", "Temporal.PlainDateTime.prototype.add()")}}
+- {{jsxref("Temporal/PlainDateTime/subtract", "Temporal.PlainDateTime.prototype.subtract()")}}
+- {{jsxref("Temporal/PlainDateTime/millisecond", "Temporal.PlainDateTime.prototype.millisecond")}}
+- {{jsxref("Temporal/PlainDateTime/microsecond", "Temporal.PlainDateTime.prototype.microsecond")}}
+- {{jsxref("Temporal/PlainDateTime/nanosecond", "Temporal.PlainDateTime.prototype.nanosecond")}}
+- {{jsxref("Temporal/PlainTime/second", "Temporal.PlainTime.prototype.second")}}

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

@@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Temporal.PlainTime.add
 
 {{JSRef}}
 
-The **`add()`** method of {{jsxref("Temporal.PlainTime")}} instances TODO
+The **`add()`** method of {{jsxref("Temporal.PlainTime")}} instances returns a new `Temporal.PlainTime` object representing this time moved forward by a given duration (in a form convertible by {{jsxref("Temporal/Duration/from", "Temporal.Duration.from()")}}), wrapping around the clock if necessary.
 
 ## Syntax
 
@@ -18,23 +18,40 @@ add(duration)
 ### Parameters
 
 - `duration`
-  - : TODO
+  - : A string, an object, or a {{jsxref("Temporal.Duration")}} instance representing a duration to add to this time. It is converted to a `Temporal.Duration` object using the same algorithm as {{jsxref("Temporal/Duration/from", "Temporal.Duration.from()")}}.
 
 ### Return value
 
-TODO
+A new `Temporal.PlainTime` object representing the time specified by the original `PlainTime`, plus the duration. Any units above `hours` are ignored, and if the time goes past midnight, it wraps around to the next day.
 
-### Exceptions
+Adding a duration is equivalent to [subtracting](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainTime/subtract) its [negation](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration/negated).
 
-TODO
+## Examples
 
-## Description
+### Adding a duration
 
-TODO
+```js
+const start = Temporal.PlainTime.from("12:34:56");
+const end = start.add({ hours: 1, minutes: 30 });
+console.log(end.toString()); // 14:04:56
 
-## Examples
+const end2 = start.add({ hours: -1, minutes: -30 });
+console.log(end2.toString()); // 11:04:56
+
+const distance = Temporal.PlainTime.from("00:00:00").until("01:23:45"); // 1h 23m 45s
+const end3 = start.add(distance);
+console.log(end3.toString()); // 13:58:41
+```
 
-TODO
+### Time wrapping
+
+If the time goes past midnight, it wraps around to the next day:
+
+```js
+const start = Temporal.PlainTime.from("12:34:56");
+const end = start.add({ hours: 12 });
+console.log(end.toString()); // 00:34:56
+```
 
 ## Specifications
 
@@ -46,4 +63,6 @@ TODO
 
 ## See also
 
-- TODO
+- {{jsxref("Temporal.PlainTime")}}
+- {{jsxref("Temporal.Duration")}}
+- {{jsxref("Temporal/PlainTime/subtract", "Temporal.PlainTime.prototype.subtract()")}}