From d579966dc2658462abb9c8d2eb4794c9110973a8 Mon Sep 17 00:00:00 2001
From: Jeff Davidson <jpd@google.com>
Date: Wed, 30 May 2018 14:04:16 -0700
Subject: [PATCH] Flesh out RetryPolicy's Javadoc.

Make it clear that there is no supported way to configure a retry
policy which will induce a delay between tries with the current API.

See #80
---
 .../java/com/android/volley/RetryPolicy.java  | 22 ++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/src/main/java/com/android/volley/RetryPolicy.java b/src/main/java/com/android/volley/RetryPolicy.java
index aa6af438..8c98d731 100644
--- a/src/main/java/com/android/volley/RetryPolicy.java
+++ b/src/main/java/com/android/volley/RetryPolicy.java
@@ -16,7 +16,27 @@
 
 package com.android.volley;
 
-/** Retry policy for a request. */
+/**
+ * Retry policy for a request.
+ *
+ * <p>A retry policy can control two parameters:
+ *
+ * <ul>
+ *   <li>The number of tries. This can be a simple counter or more complex logic based on the type
+ *       of error passed to {@link #retry(VolleyError)}, although {@link #getCurrentRetryCount()}
+ *       should always return the current retry count for logging purposes.
+ *   <li>The request timeout for each try, via {@link #getCurrentTimeout()}. In the common case that
+ *       a request times out before the response has been received from the server, retrying again
+ *       with a longer timeout can increase the likelihood of success (at the expense of causing the
+ *       user to wait longer, especially if the request still fails).
+ * </ul>
+ *
+ * <p>Note that currently, retries triggered by a retry policy are attempted immediately in sequence
+ * with no delay between them (although the time between tries may increase if the requests are
+ * timing out and {@link #getCurrentTimeout()} is returning increasing values.
+ *
+ * <p>By default, Volley uses {@link DefaultRetryPolicy}.
+ */
 public interface RetryPolicy {
 
     /** Returns the current timeout (used for logging). */