From d84d85f2de658075121e1d3a57500c839894cfdd Mon Sep 17 00:00:00 2001 From: Naoto Sato Date: Thu, 11 Jun 2026 18:26:56 +0000 Subject: [PATCH] 8386328: TemporalField.adjustInto Javadoc incorrectly uses 1-argument method signatures Reviewed-by: jlu, iris --- .../classes/java/time/temporal/Temporal.java | 6 ++--- .../java/time/temporal/TemporalAmount.java | 8 +++--- .../java/time/temporal/TemporalField.java | 26 +++++++++---------- .../java/time/temporal/TemporalQueries.java | 8 +++--- .../java/time/temporal/TemporalQuery.java | 14 +++++----- .../java/time/temporal/TemporalUnit.java | 8 +++--- 6 files changed, 35 insertions(+), 35 deletions(-) diff --git a/src/java.base/share/classes/java/time/temporal/Temporal.java b/src/java.base/share/classes/java/time/temporal/Temporal.java index e3c0a6819f6..0eb8c28f5ad 100644 --- a/src/java.base/share/classes/java/time/temporal/Temporal.java +++ b/src/java.base/share/classes/java/time/temporal/Temporal.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2012, 2019, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2012, 2026, 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 @@ -392,8 +392,8 @@ public interface Temporal extends TemporalAccessor { * The second is to use {@link TemporalUnit#between(Temporal, Temporal)}: * 
      *   // these two lines are equivalent
-     *   temporal = start.until(end, unit);
-     *   temporal = unit.between(start, end);
+     *   amount = start.until(end, unit);
+     *   amount = unit.between(start, end);
      *
* The choice should be made based on which makes the code more readable. *

diff --git a/src/java.base/share/classes/java/time/temporal/TemporalAmount.java b/src/java.base/share/classes/java/time/temporal/TemporalAmount.java index 0d8b8a96bb0..abc694957e1 100644 --- a/src/java.base/share/classes/java/time/temporal/TemporalAmount.java +++ b/src/java.base/share/classes/java/time/temporal/TemporalAmount.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2012, 2026, 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 @@ -145,9 +145,9 @@ public interface TemporalAmount { * 

      *   // These two lines are equivalent, but the second approach is recommended
      *   dateTime = amount.addTo(dateTime);
-     *   dateTime = dateTime.plus(adder);
+     *   dateTime = dateTime.plus(amount);
      *
- * It is recommended to use the second approach, {@code plus(TemporalAmount)}, + * It is recommended to use the second approach, {@code plus(amount)}, * as it is a lot clearer to read in code. * * @implSpec @@ -189,7 +189,7 @@ public interface TemporalAmount { * dateTime = amount.subtractFrom(dateTime); * dateTime = dateTime.minus(amount); * - * It is recommended to use the second approach, {@code minus(TemporalAmount)}, + * It is recommended to use the second approach, {@code minus(amount)}, * as it is a lot clearer to read in code. * * @implSpec diff --git a/src/java.base/share/classes/java/time/temporal/TemporalField.java b/src/java.base/share/classes/java/time/temporal/TemporalField.java index 54a523e64c3..4d9c620699f 100644 --- a/src/java.base/share/classes/java/time/temporal/TemporalField.java +++ b/src/java.base/share/classes/java/time/temporal/TemporalField.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2012, 2020, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2012, 2026, 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 @@ -186,10 +186,10 @@ public interface TemporalField { * The second is to use {@link TemporalAccessor#isSupported(TemporalField)}: * 
      *   // these two lines are equivalent, but the second approach is recommended
-     *   temporal = thisField.isSupportedBy(temporal);
-     *   temporal = temporal.isSupported(thisField);
+     *   supported = thisField.isSupportedBy(temporal);
+     *   supported = temporal.isSupported(thisField);
      *
- * It is recommended to use the second approach, {@code isSupported(TemporalField)}, + * It is recommended to use the second approach, {@code isSupported(thisField)}, * as it is a lot clearer to read in code. *

* Implementations should determine whether they are supported using the fields @@ -216,10 +216,10 @@ public interface TemporalField { * The second is to use {@link TemporalAccessor#range(TemporalField)}: * 

      *   // these two lines are equivalent, but the second approach is recommended
-     *   temporal = thisField.rangeRefinedBy(temporal);
-     *   temporal = temporal.range(thisField);
+     *   range = thisField.rangeRefinedBy(temporal);
+     *   range = temporal.range(thisField);
      *
- * It is recommended to use the second approach, {@code range(TemporalField)}, + * It is recommended to use the second approach, {@code range(thisField)}, * as it is a lot clearer to read in code. *

* Implementations should perform any queries or calculations using the fields @@ -244,10 +244,10 @@ public interface TemporalField { * (or {@link TemporalAccessor#get(TemporalField)}): * 

      *   // these two lines are equivalent, but the second approach is recommended
-     *   temporal = thisField.getFrom(temporal);
-     *   temporal = temporal.getLong(thisField);
+     *   value = thisField.getFrom(temporal);
+     *   value = temporal.getLong(thisField);
      *
- * It is recommended to use the second approach, {@code getLong(TemporalField)}, + * It is recommended to use the second approach, {@code getLong(thisField)}, * as it is a lot clearer to read in code. *

* Implementations should perform any queries or calculations using the fields @@ -281,10 +281,10 @@ public interface TemporalField { * The second is to use {@link Temporal#with(TemporalField, long)}: * 

      *   // these two lines are equivalent, but the second approach is recommended
-     *   temporal = thisField.adjustInto(temporal);
-     *   temporal = temporal.with(thisField);
+     *   temporal = thisField.adjustInto(temporal, newValue);
+     *   temporal = temporal.with(thisField, newValue);
      *
- * It is recommended to use the second approach, {@code with(TemporalField)}, + * It is recommended to use the second approach, {@code with(thisField, newValue)}, * as it is a lot clearer to read in code. *

* Implementations should perform any queries or calculations using the fields diff --git a/src/java.base/share/classes/java/time/temporal/TemporalQueries.java b/src/java.base/share/classes/java/time/temporal/TemporalQueries.java index c0e2eaf5908..2181011e7cb 100644 --- a/src/java.base/share/classes/java/time/temporal/TemporalQueries.java +++ b/src/java.base/share/classes/java/time/temporal/TemporalQueries.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2012, 2022, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2012, 2026, 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 @@ -94,10 +94,10 @@ import java.time.chrono.Chronology; * The second is to use {@link TemporalAccessor#query(TemporalQuery)}: * 

  *   // these two lines are equivalent, but the second approach is recommended
- *   temporal = thisQuery.queryFrom(temporal);
- *   temporal = temporal.query(thisQuery);
+ *   result = thisQuery.queryFrom(temporal);
+ *   result = temporal.query(thisQuery);
  *
- * It is recommended to use the second approach, {@code query(TemporalQuery)}, + * It is recommended to use the second approach, {@code query(thisQuery)}, * as it is a lot clearer to read in code. *

* The most common implementations are method references, such as diff --git a/src/java.base/share/classes/java/time/temporal/TemporalQuery.java b/src/java.base/share/classes/java/time/temporal/TemporalQuery.java index 96142963062..220dec994a3 100644 --- a/src/java.base/share/classes/java/time/temporal/TemporalQuery.java +++ b/src/java.base/share/classes/java/time/temporal/TemporalQuery.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2012, 2026, 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 @@ -81,10 +81,10 @@ import java.time.DateTimeException; * The second is to use {@link TemporalAccessor#query(TemporalQuery)}: * 

  *   // these two lines are equivalent, but the second approach is recommended
- *   temporal = thisQuery.queryFrom(temporal);
- *   temporal = temporal.query(thisQuery);
+ *   result = thisQuery.queryFrom(temporal);
+ *   result = temporal.query(thisQuery);
  *
- * It is recommended to use the second approach, {@code query(TemporalQuery)}, + * It is recommended to use the second approach, {@code query(thisQuery)}, * as it is a lot clearer to read in code. *

* The most common implementations are method references, such as @@ -115,10 +115,10 @@ public interface TemporalQuery { * The second is to use {@link TemporalAccessor#query(TemporalQuery)}: * 

      *   // these two lines are equivalent, but the second approach is recommended
-     *   temporal = thisQuery.queryFrom(temporal);
-     *   temporal = temporal.query(thisQuery);
+     *   result = thisQuery.queryFrom(temporal);
+     *   result = temporal.query(thisQuery);
      *
- * It is recommended to use the second approach, {@code query(TemporalQuery)}, + * It is recommended to use the second approach, {@code query(thisQuery)}, * as it is a lot clearer to read in code. * * @implSpec diff --git a/src/java.base/share/classes/java/time/temporal/TemporalUnit.java b/src/java.base/share/classes/java/time/temporal/TemporalUnit.java index 9638e30c6dd..3235fe6fcee 100644 --- a/src/java.base/share/classes/java/time/temporal/TemporalUnit.java +++ b/src/java.base/share/classes/java/time/temporal/TemporalUnit.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2012, 2025, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2012, 2026, 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 @@ -203,10 +203,10 @@ public interface TemporalUnit { * The second is to use {@link Temporal#plus(long, TemporalUnit)}: * 
      *   // these two lines are equivalent, but the second approach is recommended
-     *   temporal = thisUnit.addTo(temporal);
-     *   temporal = temporal.plus(thisUnit);
+     *   temporal = thisUnit.addTo(temporal, amount);
+     *   temporal = temporal.plus(amount, thisUnit);
      *
- * It is recommended to use the second approach, {@code plus(TemporalUnit)}, + * It is recommended to use the second approach, {@code plus(amount, thisUnit)}, * as it is a lot clearer to read in code. *

* Implementations should perform any queries or calculations using the units