From 75f1c09c1f8769df651e7c86bdeb1320a3d5f8fd Mon Sep 17 00:00:00 2001
From: Marco Ziccardi <marco.ziccard@gmail.com>
Date: Mon, 12 Oct 2015 19:05:15 +0200
Subject: [PATCH] More detailed javadoc for options.retryParams and RetryParams

---
 .../java/com/google/gcloud/RetryParams.java   | 19 ++++++++++++-------
 .../com/google/gcloud/ServiceOptions.java     |  7 ++++---
 2 files changed, 16 insertions(+), 10 deletions(-)

diff --git a/gcloud-java-core/src/main/java/com/google/gcloud/RetryParams.java b/gcloud-java-core/src/main/java/com/google/gcloud/RetryParams.java
index 0d38aea77ab0..24983326ccae 100644
--- a/gcloud-java-core/src/main/java/com/google/gcloud/RetryParams.java
+++ b/gcloud-java-core/src/main/java/com/google/gcloud/RetryParams.java
@@ -66,7 +66,6 @@ public final class RetryParams implements Serializable {
   private static final RetryParams NO_RETRIES =
       builder().retryMaxAttempts(1).retryMinAttempts(1).build();
 
-
   /**
    * RetryParams builder.
    */
@@ -206,47 +205,53 @@ public static RetryParams getDefaultInstance() {
     return DEFAULT_INSTANCE;
   }
 
+  /**
+   * Returns an instance of {@code RetryParams} where `retryMaxAttempts` and `retryMinAttempts` are
+   * set to `1`.
+   */
   public static RetryParams noRetries() {
     return NO_RETRIES;
   }
 
   /**
-   * Returns the retryMinAttempts.
+   * Returns the retryMinAttempts. Default value is {@value #DEFAULT_RETRY_MIN_ATTEMPTS}.
    */
   public int getRetryMinAttempts() {
     return retryMinAttempts;
   }
 
   /**
-   * Returns the retryMaxAttempts.
+   * Returns the retryMaxAttempts. Default value is {@value #DEFAULT_RETRY_MAX_ATTEMPTS}.
    */
   public int getRetryMaxAttempts() {
     return retryMaxAttempts;
   }
 
   /**
-   * Returns the initialRetryDelayMillis.
+   * Returns the initialRetryDelayMillis. Default value is
+   * {@value #DEFAULT_INITIAL_RETRY_DELAY_MILLIS}.
    */
   public long getInitialRetryDelayMillis() {
     return initialRetryDelayMillis;
   }
 
   /**
-   * Returns the maxRetryDelayMillis.
+   * Returns the maxRetryDelayMillis. Default values is {@value #DEFAULT_MAX_RETRY_DELAY_MILLIS}.
    */
   public long getMaxRetryDelayMillis() {
     return maxRetryDelayMillis;
   }
 
   /**
-   * Returns the maxRetryDelayBackoffFactor.
+   * Returns the maxRetryDelayBackoffFactor. Default values is
+   * {@value #DEFAULT_RETRY_DELAY_BACKOFF_FACTOR}.
    */
   public double getRetryDelayBackoffFactor() {
     return retryDelayBackoffFactor;
   }
 
   /**
-   * Returns the totalRetryPeriodMillis.
+   * Returns the totalRetryPeriodMillis. Default value is {@value #DEFAULT_TOTAL_RETRY_PERIOD_MILLIS}.
    */
   public long getTotalRetryPeriodMillis() {
     return totalRetryPeriodMillis;
diff --git a/gcloud-java-core/src/main/java/com/google/gcloud/ServiceOptions.java b/gcloud-java-core/src/main/java/com/google/gcloud/ServiceOptions.java
index c70975502a06..b80378ccd72c 100644
--- a/gcloud-java-core/src/main/java/com/google/gcloud/ServiceOptions.java
+++ b/gcloud-java-core/src/main/java/com/google/gcloud/ServiceOptions.java
@@ -16,7 +16,6 @@
 
 package com.google.gcloud;
 
-
 import static com.google.common.base.MoreObjects.firstNonNull;
 import static com.google.common.base.Preconditions.checkNotNull;
 import static java.nio.charset.StandardCharsets.UTF_8;
@@ -167,7 +166,8 @@ public B authCredentials(AuthCredentials authCredentials) {
     }
 
     /**
-     * Sets configuration parameters for request retries.
+     * Sets configuration parameters for request retries. If no configuration is set
+     * {@link RetryParams#noRetries()} is used.
      *
      * @return the builder.
      */
@@ -367,7 +367,8 @@ public AuthCredentials authCredentials() {
   }
 
   /**
-   * Returns configuration parameters for request retries.
+   * Returns configuration parameters for request retries. By default requests are not retried:
+   * {@link RetryParams#noRetries()} is used.
    */
   public RetryParams retryParams() {
     return retryParams != null ? retryParams : RetryParams.noRetries();