docs: Clarify that the from() overflow option doesn't apply to strings

Closes: #797

Author: ptomato

docs/plaindate.md

@@ -55,7 +55,7 @@ date = new Temporal.PlainDate(2020, 3, 14); // => 2020-03-14
 - `thing`: The value representing the desired date.
 - `options` (optional object): An object with properties representing options for constructing the date.
   The following options are recognized:
-  - `overflow` (string): How to deal with out-of-range values in `thing`.
+  - `overflow` (string): How to deal with out-of-range values if `thing` is an object.
     Allowed values are `constrain` and `reject`.
     The default is `constrain`.
 
@@ -73,11 +73,13 @@ Any non-object value is converted to a string, which is expected to be in ISO 86
 Any time or time zone part is optional and will be ignored.
 If the string isn't valid according to ISO 8601, then a `RangeError` will be thrown regardless of the value of `overflow`.
 
-The `overflow` option works as follows:
+The `overflow` option works as follows, if `thing` is an object:
 
 - In `constrain` mode (the default), any out-of-range values are clamped to the nearest in-range value.
 - In `reject` mode, the presence of out-of-range values will cause the function to throw a `RangeError`.
 
+The `overflow` option is ignored if `thing` is a string.
+
 Additionally, if the result is earlier or later than the range of dates that `Temporal.PlainDate` can represent (approximately half a million years centered on the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time)), then this function will throw a `RangeError` regardless of `overflow`.
 
 > **NOTE**: The allowed values for the `thing.month` property start at 1, which is different from legacy `Date` where months are represented by zero-based indices (0 to 11).

docs/plaindatetime.md

@@ -83,7 +83,7 @@ datetime = new Temporal.PlainDateTime(2020, 3, 14, 13, 37); // => 2020-03-14T13:
 - `thing`: The value representing the desired date and time.
 - `options` (optional object): An object with properties representing options for constructing the date and time.
   The following options are recognized:
-  - `overflow` (string): How to deal with out-of-range values in `thing`.
+  - `overflow` (string): How to deal with out-of-range values if `thing` is an object.
     Allowed values are `constrain` and `reject`.
     The default is `constrain`.
 
@@ -103,11 +103,13 @@ Any non-object value is converted to a string, which is expected to be in ISO 86
 Any time zone part is optional and will be ignored.
 If the string isn't valid according to ISO 8601, then a `RangeError` will be thrown regardless of the value of `overflow`.
 
-The `overflow` option works as follows:
+The `overflow` option works as follows, if `thing` is an object:
 
 - In `constrain` mode (the default), any out-of-range values are clamped to the nearest in-range value.
 - In `reject` mode, the presence of out-of-range values will cause the function to throw a `RangeError`.
 
+The `overflow` option is ignored if `thing` is a string.
+
 Additionally, if the result is earlier or later than the range of dates that `Temporal.PlainDateTime` can represent (approximately half a million years centered on the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time)), then this method will throw a `RangeError` regardless of `overflow`.
 
 > **NOTE**: Although Temporal does not deal with leap seconds, dates coming from other software may have a `second` value of 60.

docs/plainmonthday.md

@@ -55,7 +55,7 @@ md = new Temporal.PlainMonthDay(2, 29); // => 02-29
 - `thing`: The value representing the desired date.
 - `options` (optional object): An object with properties representing options for constructing the date.
   The following options are recognized:
-  - `overflow` (string): How to deal with out-of-range values in `thing`.
+  - `overflow` (string): How to deal with out-of-range values if `thing` is an object.
     Allowed values are `constrain` and `reject`.
     The default is `constrain`.
 
@@ -76,12 +76,14 @@ For other calendars, the year and calendar are also parsed in addition to month
 Any other parts of the string are optional and will be ignored.
 If the string isn't valid according to ISO 8601, then a `RangeError` will be thrown regardless of the value of `overflow`.
 
-The `overflow` option works as follows:
+The `overflow` option works as follows, if `thing` is an object:
 
 - In `constrain` mode (the default), any out-of-range values are clamped to the nearest in-range value, with "nearest" defined by the calendar.
 - In `reject` mode, the presence of out-of-range values will cause the function to throw a `RangeError`.
   If `day`, `month` and `year` are provided, that calendar date must exist in the provided calendar or a `RangeError` will be thrown.
 
+The `overflow` option is ignored if `thing` is a string.
+
 > **NOTE**: The allowed values for the `thing.month` property start at 1, which is different from legacy `Date` where months are represented by zero-based indices (0 to 11).
 
 Example usage:

docs/plaintime.md

@@ -49,7 +49,7 @@ time = new Temporal.PlainTime(13, 37); // => 13:37
 - `thing`: The value representing the desired time.
 - `options` (optional object): An object with properties representing options for constructing the time.
   The following options are recognized:
-  - `overflow` (optional string): How to deal with out-of-range values of the other parameters.
+  - `overflow` (optional string): How to deal with out-of-range values if `thing` is an object.
     Allowed values are `constrain` and `reject`.
     The default is `constrain`.
 
@@ -65,11 +65,13 @@ If the `calendar` property is present, it must be the string `'iso8601'` or the
 Any non-object value will be converted to a string, which is expected to be in ISO 8601 format.
 If the string designates a date or a time zone, they will be ignored.
 
-The `overflow` option works as follows:
+The `overflow` option works as follows, if `thing` is an object:
 
 - In `constrain` mode (the default), any out-of-range values are clamped to the nearest in-range value.
 - In `reject` mode, the presence of out-of-range values will cause the function to throw a `RangeError`.
 
+The `overflow` option is ignored if `thing` is a string.
+
 > **NOTE**: Although Temporal does not deal with leap seconds, times coming from other software may have a `second` value of 60.
 > In the default `constrain` mode, this will be converted to 59.
 > In `reject` mode, the constructor will throw, so if you have to interoperate with times that may contain leap seconds, don't use `reject`.

docs/plainyearmonth.md

@@ -58,7 +58,7 @@ ym = new Temporal.PlainYearMonth(2019, 6);
 - `thing`: The value representing the desired month.
 - `options` (optional object): An object with properties representing options for constructing the date.
   The following options are recognized:
-  - `overflow` (string): How to deal with out-of-range values in `thing`.
+  - `overflow` (string): How to deal with out-of-range values if `thing` is an object.
     Allowed values are `constrain` and `reject`.
     The default is `constrain`.
 
@@ -76,11 +76,13 @@ Any non-object value is converted to a string, which is expected to be in ISO 86
 Any parts of the string other than the year and the month are optional and will be ignored.
 If the string isn't valid according to ISO 8601, then a `RangeError` will be thrown regardless of the value of `overflow`.
 
-The `overflow` option works as follows:
+The `overflow` option works as follows, if `thing` is an object:
 
 - In `constrain` mode (the default), any out-of-range values are clamped to the nearest in-range value.
 - In `reject` mode, the presence of out-of-range values will cause the function to throw a `RangeError`.
 
+The `overflow` option is ignored if `thing` is a string.
+
 Additionally, if the result is earlier or later than the range of dates that `Temporal.PlainYearMonth` can represent (approximately half a million years centered on the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time)), then this method will throw a `RangeError` regardless of `overflow`.
 
 > **NOTE**: The allowed values for the `thing.month` property start at 1, which is different from legacy `Date` where months are represented by zero-based indices (0 to 11).

docs/zoneddatetime.md

@@ -60,7 +60,7 @@ new Temporal.ZonedDateTime(0n, 'America/Los_Angeles'); // same, but shorter
 
 - `thing`: The value representing the desired date, time, time zone, and calendar.
 - `options` (optional object): An object which may have some or all of the following properties:
-  - `overflow` (string): How to deal with out-of-range values in `thing`.
+  - `overflow` (string): How to deal with out-of-range values if `thing` is an object.
     Allowed values are `'constrain'` and `'reject'`.
     The default is `'constrain'`.
   - `disambiguation` (string): How to disambiguate if the date and time given by `zonedDateTime` does not exist in the time zone, or exists more than once.
@@ -120,11 +120,13 @@ Note that using `Temporal.ZonedDateTime` with a single-offset time zone will not
 Therefore, using offset time zones with `Temporal.ZonedDateTime` is relatively unusual.
 Instead of using `Temporal.ZonedDateTime` with an offset time zone, it may be easier for most use cases to use `Temporal.PlainDateTime` and/or `Temporal.Instant` instead.
 
-The `overflow` option works as follows:
+The `overflow` option works as follows, if `thing` is an object:
 
 - In `'constrain'` mode (the default), any out-of-range values are clamped to the nearest in-range value.
 - In `'reject'` mode, the presence of out-of-range values will cause the function to throw a `RangeError`.
 
+The `overflow` option is ignored if `thing` is a string.
+
 Additionally, if the result is earlier or later than the range of dates that `Temporal.PlainDateTime` can represent (approximately half a million years centered on the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time)), then this method will throw a `RangeError` regardless of `overflow`.
 
 > **NOTE**: Although Temporal does not deal with leap seconds, dates coming from other software may have a `second` value of 60.