8367704: Fix minor documentation issues in java.time.**

Reviewed-by: naoto, rriggs

Author: pavelrappo

src/java.base/share/classes/java/time/Duration.java

@@ -172,7 +172,7 @@ private static class Lazy {
      * Obtains a {@code Duration} representing a number of standard 24 hour days.
      * <p>
      * The seconds are calculated based on the standard definition of a day,
-     * where each day is 86400 seconds which implies a 24 hour day.
+     * where each day is 86,400 seconds which implies a 24 hour day.
      * The nanosecond in second field is set to zero.
      *
      * @param days  the number of days, positive or negative
@@ -187,7 +187,7 @@ public static Duration ofDays(long days) {
      * Obtains a {@code Duration} representing a number of standard hours.
      * <p>
      * The seconds are calculated based on the standard definition of an hour,
-     * where each hour is 3600 seconds.
+     * where each hour is 3,600 seconds.
      * The nanosecond in second field is set to zero.
      *
      * @param hours  the number of hours, positive or negative
@@ -375,8 +375,8 @@ public static Duration from(TemporalAmount amount) {
      * <pre>
      *    "PT20.345S" -- parses as "20.345 seconds"
      *    "PT15M"     -- parses as "15 minutes" (where a minute is 60 seconds)
-     *    "PT10H"     -- parses as "10 hours" (where an hour is 3600 seconds)
-     *    "P2D"       -- parses as "2 days" (where a day is 24 hours or 86400 seconds)
+     *    "PT10H"     -- parses as "10 hours" (where an hour is 3,600 seconds)
+     *    "P2D"       -- parses as "2 days" (where a day is 24 hours or 86,400 seconds)
      *    "P2DT3H4M"  -- parses as "2 days, 3 hours and 4 minutes"
      *    "PT-6H3M"    -- parses as "-6 hours and +3 minutes"
      *    "-PT6H3M"    -- parses as "-6 hours and -3 minutes"
@@ -477,7 +477,7 @@ private static Duration create(boolean negate, long daysAsSecs, long hoursAsSecs
      * {@link ChronoField#NANO_OF_SECOND NANO_OF_SECOND} field should be supported.
      * <p>
      * The result of this method can be a negative duration if the end is before the start.
-     * To guarantee to obtain a positive duration call {@link #abs()} on the result.
+     * To guarantee a positive duration, call {@link #abs()} on the result.
      *
      * @param startInclusive  the start instant, inclusive, not null
      * @param endExclusive  the end instant, exclusive, not null
@@ -752,7 +752,7 @@ public Duration plus(long amountToAdd, TemporalUnit unit) {
     /**
      * Returns a copy of this duration with the specified duration in standard 24 hour days added.
      * <p>
-     * The number of days is multiplied by 86400 to obtain the number of seconds to add.
+     * The number of days is multiplied by 86,400 to obtain the number of seconds to add.
      * This is based on the standard definition of a day as 24 hours.
      * <p>
      * This instance is immutable and unaffected by this method call.
@@ -893,7 +893,7 @@ public Duration minus(long amountToSubtract, TemporalUnit unit) {
     /**
      * Returns a copy of this duration with the specified duration in standard 24 hour days subtracted.
      * <p>
-     * The number of days is multiplied by 86400 to obtain the number of seconds to subtract.
+     * The number of days is multiplied by 86,400 to obtain the number of seconds to subtract.
      * This is based on the standard definition of a day as 24 hours.
      * <p>
      * This instance is immutable and unaffected by this method call.
@@ -909,7 +909,7 @@ public Duration minusDays(long daysToSubtract) {
     /**
      * Returns a copy of this duration with the specified duration in hours subtracted.
      * <p>
-     * The number of hours is multiplied by 3600 to obtain the number of seconds to subtract.
+     * The number of hours is multiplied by 3,600 to obtain the number of seconds to subtract.
      * <p>
      * This instance is immutable and unaffected by this method call.
      *
@@ -924,7 +924,7 @@ public Duration minusHours(long hoursToSubtract) {
     /**
      * Returns a copy of this duration with the specified duration in minutes subtracted.
      * <p>
-     * The number of hours is multiplied by 60 to obtain the number of seconds to subtract.
+     * The number of minutes is multiplied by 60 to obtain the number of seconds to subtract.
      * <p>
      * This instance is immutable and unaffected by this method call.
      *
@@ -1165,7 +1165,7 @@ public Temporal subtractFrom(Temporal temporal) {
      * Gets the number of days in this duration.
      * <p>
      * This returns the total number of days in the duration by dividing the
-     * number of seconds by 86400.
+     * number of seconds by 86,400.
      * This is based on the standard definition of a day as 24 hours.
      * <p>
      * This instance is immutable and unaffected by this method call.
@@ -1180,7 +1180,7 @@ public long toDays() {
      * Gets the number of hours in this duration.
      * <p>
      * This returns the total number of hours in the duration by dividing the
-     * number of seconds by 3600.
+     * number of seconds by 3,600.
      * <p>
      * This instance is immutable and unaffected by this method call.
      *
@@ -1272,7 +1272,7 @@ public long toNanos() {
      * Extracts the number of days in the duration.
      * <p>
      * This returns the total number of days in the duration by dividing the
-     * number of seconds by 86400.
+     * number of seconds by 86,400.
      * This is based on the standard definition of a day as 24 hours.
      * <p>
      * This instance is immutable and unaffected by this method call.
@@ -1476,10 +1476,10 @@ public int hashCode() {
      * <p>
      * Examples:
      * <pre>
-     *    "20.345 seconds"                 -- "PT20.345S
+     *    "20.345 seconds"                 -- "PT20.345S"
      *    "15 minutes" (15 * 60 seconds)   -- "PT15M"
-     *    "10 hours" (10 * 3600 seconds)   -- "PT10H"
-     *    "2 days" (2 * 86400 seconds)     -- "PT48H"
+     *    "10 hours" (10 * 3,600 seconds)  -- "PT10H"
+     *    "2 days" (2 * 86,400 seconds)    -- "PT48H"
      * </pre>
      * Note that multiples of 24 hours are not output as days to avoid confusion
      * with {@code Period}.

src/java.base/share/classes/java/time/Instant.java

@@ -114,15 +114,15 @@
  * <p>
  * The length of the solar day is the standard way that humans measure time.
  * This has traditionally been subdivided into 24 hours of 60 minutes of 60 seconds,
- * forming a 86400 second day.
+ * forming an 86,400 second day.
  * <p>
  * Modern timekeeping is based on atomic clocks which precisely define an SI second
  * relative to the transitions of a Caesium atom. The length of an SI second was defined
- * to be very close to the 86400th fraction of a day.
+ * to be very close to the 86,400th fraction of a day.
  * <p>
  * Unfortunately, as the Earth rotates the length of the day varies.
  * In addition, over time the average length of the day is getting longer as the Earth slows.
- * As a result, the length of a solar day in 2012 is slightly longer than 86400 SI seconds.
+ * As a result, the length of a solar day in 2012 is slightly longer than 86,400 SI seconds.
  * The actual length of any given day and the amount by which the Earth is slowing
  * are not predictable and can only be determined by measurement.
  * The UT1 time-scale captures the accurate length of day, but is only available some
@@ -131,7 +131,7 @@
  * The UTC time-scale is a standard approach to bundle up all the additional fractions
  * of a second from UT1 into whole seconds, known as <i>leap-seconds</i>.
  * A leap-second may be added or removed depending on the Earth's rotational changes.
- * As such, UTC permits a day to have 86399 SI seconds or 86401 SI seconds where
+ * As such, UTC permits a day to have 86,399 SI seconds or 86,401 SI seconds where
  * necessary in order to keep the day aligned with the Sun.
  * <p>
  * The modern UTC time-scale was introduced in 1972, introducing the concept of whole leap-seconds.
@@ -143,7 +143,7 @@
  * Given the complexity of accurate timekeeping described above, this Java API defines
  * its own time-scale, the <i>Java Time-Scale</i>.
  * <p>
- * The Java Time-Scale divides each calendar day into exactly 86400
+ * The Java Time-Scale divides each calendar day into exactly 86,400
  * subdivisions, known as seconds.  These seconds may differ from the
  * SI second.  It closely matches the de facto international civil time
  * scale, the definition of which changes from time to time.
@@ -171,7 +171,7 @@
  * This is identical to UTC on days that do not have a leap second.
  * On days that do have a leap second, the leap second is spread equally
  * over the last 1000 seconds of the day, maintaining the appearance of
- * exactly 86400 seconds per day.
+ * exactly 86,400 seconds per day.
  * <p>
  * For the segment prior to 1972-11-03, extending back arbitrarily far,
  * the consensus international time scale is defined to be UT1, applied

src/java.base/share/classes/java/time/Period.java

@@ -765,7 +765,7 @@ public Period minusMonths(long monthsToSubtract) {
      * <p>
      * This instance is immutable and unaffected by this method call.
      *
-     * @param daysToSubtract  the months to subtract, positive or negative
+     * @param daysToSubtract  the days to subtract, positive or negative
      * @return a {@code Period} based on this period with the specified days subtracted, not null
      * @throws ArithmeticException if numeric overflow occurs
      */

src/java.base/share/classes/java/time/ZoneOffset.java

@@ -417,9 +417,9 @@ private static int totalSeconds(int hours, int minutes, int seconds) {
     /**
      * Obtains an instance of {@code ZoneOffset} specifying the total offset in seconds
      * <p>
-     * The offset must be in the range {@code -18:00} to {@code +18:00}, which corresponds to -64800 to +64800.
+     * The offset must be in the range {@code -18:00} to {@code +18:00}, which corresponds to -64,800 to +64,800.
      *
-     * @param totalSeconds  the total time-zone offset in seconds, from -64800 to +64800
+     * @param totalSeconds  the total time-zone offset in seconds, from -64,800 to +64,800
      * @return the ZoneOffset, not null
      * @throws DateTimeException if the offset is not in the required range
      */
@@ -450,7 +450,7 @@ public static ZoneOffset ofTotalSeconds(int totalSeconds) {
     /**
      * Constructor.
      *
-     * @param totalSeconds  the total time-zone offset in seconds, from -64800 to +64800
+     * @param totalSeconds  the total time-zone offset in seconds, from -64,800 to +64,800
      */
     private ZoneOffset(int totalSeconds) {
         this.totalSeconds = totalSeconds;

src/java.base/share/classes/java/time/ZonedDateTime.java

@@ -136,7 +136,7 @@
  * For Overlaps, the general strategy is that if the local date-time falls in the
  * middle of an Overlap, then the previous offset will be retained. If there is no
  * previous offset, or the previous offset is invalid, then the earlier offset is
- * used, typically "summer" time.. Two additional methods,
+ * used, typically "summer" time. Two additional methods,
  * {@link #withEarlierOffsetAtOverlap()} and {@link #withLaterOffsetAtOverlap()},
  * help manage the case of an overlap.
  * <p>
@@ -246,7 +246,7 @@ public static ZonedDateTime now(Clock clock) {
      * Time-zone rules, such as daylight savings, mean that not every local date-time
      * is valid for the specified zone, thus the local date-time may be adjusted.
      * <p>
-     * The local date time and first combined to form a local date-time.
+     * The local date and time are first combined to form a local date-time.
      * The local date-time is then resolved to a single instant on the time-line.
      * This is achieved by finding a valid offset from UTC/Greenwich for the local
      * date-time as defined by the {@link ZoneRules rules} of the zone ID.
@@ -263,7 +263,7 @@ public static ZonedDateTime now(Clock clock) {
      * @param date  the local date, not null
      * @param time  the local time, not null
      * @param zone  the time-zone, not null
-     * @return the offset date-time, not null
+     * @return the zoned date-time, not null
      */
     public static ZonedDateTime of(LocalDate date, LocalTime time, ZoneId zone) {
         return of(LocalDateTime.of(date, time), zone);
@@ -333,7 +333,7 @@ public static ZonedDateTime of(LocalDateTime localDateTime, ZoneId zone) {
      * @param second  the second-of-minute to represent, from 0 to 59
      * @param nanoOfSecond  the nano-of-second to represent, from 0 to 999,999,999
      * @param zone  the time-zone, not null
-     * @return the offset date-time, not null
+     * @return the zoned date-time, not null
      * @throws DateTimeException if the value of any field is out of range, or
      *  if the day-of-month is invalid for the month-year
      */

src/java.base/share/classes/java/time/package-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -65,7 +65,7 @@
  * The main API for dates, times, instants, and durations.
  * </p>
  * <p>
- * The classes defined here represent the principle date-time concepts,
+ * The classes defined here represent the principal date-time concepts,
  * including instants, durations, dates, times, time-zones and periods.
  * They are based on the ISO calendar system, which is the <i>de facto</i> world
  * calendar following the proleptic Gregorian rules.
@@ -150,7 +150,7 @@
  * </p>
  * <p>
  * {@link java.time.OffsetTime} stores a time and offset from UTC without a date.
- * This stores a date like '11:30+01:00'.
+ * This stores a time like '11:30+01:00'.
  * The {@link java.time.ZoneOffset ZoneOffset} is of the form '+01:00'.
  * </p>
  * <p>
@@ -249,7 +249,7 @@
  * <p>
  * Multiple calendar systems is an awkward addition to the design challenges.
  * The first principle is that most users want the standard ISO calendar system.
- * As such, the main classes are ISO-only. The second principle is that most of those that want a
+ * As such, the main classes are ISO-only. The second principle is that most of those who want a
  * non-ISO calendar system want it for user interaction, thus it is a UI localization issue.
  * As such, date and time objects should be held as ISO objects in the data model and persistent
  * storage, only being converted to and from a local calendar for display.

src/java.base/share/classes/java/time/temporal/ChronoField.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -599,7 +599,7 @@ public enum ChronoField implements TemporalField {
      * A {@link ZoneOffset} represents the period of time that local time differs from UTC/Greenwich.
      * This is usually a fixed number of hours and minutes.
      * It is equivalent to the {@link ZoneOffset#getTotalSeconds() total amount} of the offset in seconds.
-     * For example, during the winter Paris has an offset of {@code +01:00}, which is 3600 seconds.
+     * For example, during the winter, Paris has an offset of {@code +01:00}, which is 3,600 seconds.
      * <p>
      * This field is strictly defined to have the same meaning in all calendar systems.
      * This is necessary to ensure interoperation between calendars.

src/java.base/share/classes/java/time/temporal/ValueRange.java

@@ -78,7 +78,7 @@
  * Only the minimum and maximum values are provided.
  * It is possible for there to be invalid values within the outer range.
  * For example, a weird field may have valid values of 1, 2, 4, 6, 7, thus
- * have a range of '1 - 7', despite that fact that values 3 and 5 are invalid.
+ * have a range of '1 - 7', despite the fact that values 3 and 5 are invalid.
  * <p>
  * Instances of this class are not tied to a specific field.
  *