Improve Javadoc for request-level timeout (#3771)

* Improve Javadoc for request-level timeout

* Update docs

* Fix checkstyle

Author: zoewangg

core/sdk-core/src/main/java/software/amazon/awssdk/core/RequestOverrideConfiguration.java

@@ -27,6 +27,7 @@
 import java.util.function.Consumer;
 import software.amazon.awssdk.annotations.Immutable;
 import software.amazon.awssdk.annotations.SdkPublicApi;
+import software.amazon.awssdk.core.client.config.ClientOverrideConfiguration;
 import software.amazon.awssdk.core.interceptor.ExecutionAttribute;
 import software.amazon.awssdk.core.interceptor.ExecutionAttributes;
 import software.amazon.awssdk.core.signer.Signer;
@@ -333,6 +334,10 @@ default B putRawQueryParameter(String name, String value) {
          * <p>This may be used together with {@link #apiCallAttemptTimeout()} to enforce both a timeout on each individual HTTP
          * request (i.e. each retry) and the total time spent on all requests across retries (i.e. the 'api call' time).
          *
+         * <p>
+         * Note that this timeout takes precedence over the value configured at client level via
+         * {@link ClientOverrideConfiguration.Builder#apiCallTimeout(Duration)}.
+         *
          * @see RequestOverrideConfiguration#apiCallTimeout()
          */
         B apiCallTimeout(Duration apiCallTimeout);
@@ -351,6 +356,10 @@ default B putRawQueryParameter(String name, String value) {
          * <p>This may be used together with {@link #apiCallTimeout()} to enforce both a timeout on each individual HTTP
          * request (i.e. each retry) and the total time spent on all requests across retries (i.e. the 'api call' time).
          *
+         * <p>
+         * Note that this timeout takes precedence over the value configured at client level via
+         * {@link ClientOverrideConfiguration.Builder#apiCallAttemptTimeout(Duration)}.
+         *
          * @see RequestOverrideConfiguration#apiCallAttemptTimeout()
          */
         B apiCallAttemptTimeout(Duration apiCallAttemptTimeout);

core/sdk-core/src/main/java/software/amazon/awssdk/core/client/config/ClientOverrideConfiguration.java

@@ -26,6 +26,7 @@
 import java.util.function.Consumer;
 import software.amazon.awssdk.annotations.SdkPublicApi;
 import software.amazon.awssdk.annotations.ToBuilderIgnoreField;
+import software.amazon.awssdk.core.RequestOverrideConfiguration;
 import software.amazon.awssdk.core.interceptor.ExecutionAttribute;
 import software.amazon.awssdk.core.interceptor.ExecutionAttributes;
 import software.amazon.awssdk.core.interceptor.ExecutionInterceptor;
@@ -372,6 +373,10 @@ default Builder retryPolicy(RetryMode retryMode) {
          * <p>This may be used together with {@link #apiCallAttemptTimeout()} to enforce both a timeout on each individual HTTP
          * request (i.e. each retry) and the total time spent on all requests across retries (i.e. the 'api call' time).
          *
+         * <p>
+         * You can also configure it on a per-request basis via
+         * {@link RequestOverrideConfiguration.Builder#apiCallTimeout(Duration)}.
+         * Note that request-level timeout takes precedence.
          *
          * @see ClientOverrideConfiguration#apiCallTimeout()
          */
@@ -394,6 +399,11 @@ default Builder retryPolicy(RetryMode retryMode) {
          * <p>This may be used together with {@link #apiCallTimeout()} to enforce both a timeout on each individual HTTP
          * request (i.e. each retry) and the total time spent on all requests across retries (i.e. the 'api call' time).
          *
+         * <p>
+         * You can also configure it on a per-request basis via
+         * {@link RequestOverrideConfiguration.Builder#apiCallAttemptTimeout(Duration)}.
+         * Note that request-level timeout takes precedence.
+         *
          * @see ClientOverrideConfiguration#apiCallAttemptTimeout()
          */
         Builder apiCallAttemptTimeout(Duration apiCallAttemptTimeout);