Merge pull request #35844 from Ladicek/fix-duration-format-description

Improve description of the duration format in configuration documentation

core/processor/src/main/java/io/quarkus/annotation/processor/Constants.java

@@ -106,13 +106,20 @@ final public class Constants {
             "\n[id='" + DURATION_NOTE_ANCHOR + "']\n" +
             ".About the Duration format\n" +
             "====\n" +
-            "The format for durations uses the standard `java.time.Duration` format.\n" +
-            "You can learn more about it in the link:https://docs.oracle.com/javase/8/docs/api/java/time/Duration.html#parse-java.lang.CharSequence-[Duration#parse() javadoc].\n"
+            "To write duration values, use the standard `java.time.Duration` format.\n" +
+            "See the link:https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/Duration.html#parse(java.lang.CharSequence)[Duration#parse() javadoc] for more information.\n"
             +
             "\n" +
-            "You can also provide duration values starting with a number.\n" +
-            "In this case, if the value consists only of a number, the converter treats the value as seconds.\n" +
-            "Otherwise, `PT` is implicitly prepended to the value to obtain a standard `java.time.Duration` format.\n" +
+            "You can also use a simplified format, starting with a number:\n" +
+            "\n" +
+            "* If the value is only a number, it represents time in seconds.\n" +
+            "* If the value is a number followed by `ms`, it represents time in milliseconds.\n" +
+            "\n" +
+            "In other cases, the simplified format is translated to the `java.time.Duration` format for parsing:\n" +
+            "\n" +
+            "* If the value is a number followed by `h`, `m`, or `s`, it is prefixed with `PT`.\n" +
+            "* If the value is a number followed by `d`, it is prefixed with `P`" +
+            ".\n" +
             "====\n" +
             "endif::no-duration-note[]\n";
 

core/runtime/src/main/java/io/quarkus/runtime/configuration/DurationConverter.java

@@ -28,25 +28,43 @@ public DurationConverter() {
     }
 
     /**
-     * The converter accepts a value which start with a number by implicitly appending `PT` to it or `P` for days.
-     * If the value consists only of a number, it implicitly treats the value as seconds.
-     * Otherwise, tries to convert the value assuming that it is in the accepted ISO-8601 duration format.
+     * If the {@code value} starts with a number, then:
+     * <ul>
+     * <li>If the value is only a number, it is treated as a number of seconds.</li>
+     * <li>If the value is a number followed by {@code ms}, it is treated as a number of milliseconds.</li>
+     * <li>If the value is a number followed by {@code h}, {@code m}, or {@code s}, it is prefixed with {@code PT}
+     * and {@link Duration#parse(CharSequence)} is called.</li>
+     * <li>If the value is a number followed by {@code d}, it is prefixed with {@code P}
+     * and {@link Duration#parse(CharSequence)} is called.</li>
+     * </ul>
      *
-     * @param value duration as String
-     * @return {@link Duration}
+     * Otherwise, {@link Duration#parse(CharSequence)} is called.
+     *
+     * @param value a string duration
+     * @return the parsed {@link Duration}
+     * @throws IllegalArgumentException in case of parse failure
      */
     @Override
     public Duration convert(String value) {
         return parseDuration(value);
     }
 
     /**
-     * Converts a value which start with a number by implicitly appending `PT` to it or `P` for days.
-     * If the value consists only of a number, it implicitly treats the value as seconds.
-     * Otherwise, tries to convert the value assuming that it is in the accepted ISO-8601 duration format.
+     * If the {@code value} starts with a number, then:
+     * <ul>
+     * <li>If the value is only a number, it is treated as a number of seconds.</li>
+     * <li>If the value is a number followed by {@code ms}, it is treated as a number of milliseconds.</li>
+     * <li>If the value is a number followed by {@code h}, {@code m}, or {@code s}, it is prefixed with {@code PT}
+     * and {@link Duration#parse(CharSequence)} is called.</li>
+     * <li>If the value is a number followed by {@code d}, it is prefixed with {@code P}
+     * and {@link Duration#parse(CharSequence)} is called.</li>
+     * </ul>
+     *
+     * Otherwise, {@link Duration#parse(CharSequence)} is called.
      *
-     * @param value duration as String
-     * @return {@link Duration}
+     * @param value a string duration
+     * @return the parsed {@link Duration}
+     * @throws IllegalArgumentException in case of parse failure
      */
     public static Duration parseDuration(String value) {
         value = value.trim();

docs/src/main/asciidoc/_includes/duration-format-note.adoc

@@ -1,10 +1,15 @@
 [NOTE]
 ====
-The format for durations uses the standard `java.time.Duration` format.
-You can learn more about it in the link:https://docs.oracle.com/javase/8/docs/api/java/time/Duration.html#parse-java.lang.CharSequence-[Duration#parse() javadoc].
+To write duration values, use the standard `java.time.Duration` format.
+See the link:https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/Duration.html#parse(java.lang.CharSequence)[Duration#parse() javadoc] for more information.
 
-You can also provide duration values starting with a number.
-In this case, if the value consists only of a number, the converter treats the value as seconds.
-Otherwise, `PT` for seconds, minute and hours or `P` for days are implicitly prepended to the value to obtain a standard `java.time.Duration` format.
-Milliseconds are also supported by implicitly using `Duration.ofMillis()`
+You can also use a simplified format, starting with a number:
+
+* If the value is only a number, it represents time in seconds.
+* If the value is a number followed by `ms`, it represents time in milliseconds.
+
+In other cases, the simplified format is translated to the `java.time.Duration` format for parsing:
+
+* If the value is a number followed by `h`, `m`, or `s`, it is prefixed with `PT`.
+* If the value is a number followed by `d`, it is prefixed with `P`.
 ====

extensions/grpc/runtime/src/main/java/io/quarkus/grpc/runtime/config/GrpcClientConfiguration.java

@@ -188,10 +188,6 @@ public class GrpcClientConfiguration {
 
     /**
      * The deadline used for each call.
-     * <p>
-     * The format uses the standard {@link java.time.Duration} format. You can also provide duration values starting with a
-     * number. In this case, if the value consists only of a number, the converter treats the value as seconds. Otherwise,
-     * {@code PT} is implicitly prepended to the value to obtain a standard {@link java.time.Duration} format.
      */
     @ConfigItem
     public Optional<Duration> deadline;