Improve API documentation
As requested by API council, this commit:
- Adds RFC links for acronyms like IKE and SA in IkeSessionCallback and
ChildSessionCallback
- Improve documentation of setRetransmissionTimeoutsMillis to explicitly
explain the meaning of the order of the ints in the input array
Bug: 175706146
Bug: 185365945
Test: make
Change-Id: Ibc906c18b40b2362ced6b6fa29c5c7e90710d919
diff --git a/src/java/android/net/ipsec/ike/ChildSessionCallback.java b/src/java/android/net/ipsec/ike/ChildSessionCallback.java
index c2358d8..562c55a 100644
--- a/src/java/android/net/ipsec/ike/ChildSessionCallback.java
+++ b/src/java/android/net/ipsec/ike/ChildSessionCallback.java
@@ -34,6 +34,11 @@
*
* <p>{@link ChildSessionCallback}s are also used for identifying Child Sessions. It is required
* when a caller wants to delete a specific Child Session.
+ *
+ * @see <a href="https://tools.ietf.org/html/rfc7296">RFC 7296, Internet Key Exchange Protocol
+ * Version 2 (IKEv2)</a>
+ * @see <a href="https://tools.ietf.org/html/rfc4301">RFC 4301, Security Architecture for the
+ * Internet Protocol (IKEv2)</a>
*/
// Using interface instead of abstract class to indicate this callback does not have any state or
// implementation.
diff --git a/src/java/android/net/ipsec/ike/IkeSessionCallback.java b/src/java/android/net/ipsec/ike/IkeSessionCallback.java
index 4a4d6b0..26b3cfb 100644
--- a/src/java/android/net/ipsec/ike/IkeSessionCallback.java
+++ b/src/java/android/net/ipsec/ike/IkeSessionCallback.java
@@ -28,6 +28,9 @@
* <p>{@link IkeSessionCallback} MUST be unique to each {@link IkeSession}. It is registered when
* callers are requesting a new {@link IkeSession}. It is automatically unregistered when an {@link
* IkeSession} is closed.
+ *
+ * @see <a href="https://tools.ietf.org/html/rfc7296">RFC 7296, Internet Key Exchange Protocol
+ * Version 2 (IKEv2)</a>
*/
// Using interface instead of abstract class to indicate this callback does not have any state or
// implementation.
diff --git a/src/java/android/net/ipsec/ike/IkeSessionParams.java b/src/java/android/net/ipsec/ike/IkeSessionParams.java
index 6c233da..62dc13b 100644
--- a/src/java/android/net/ipsec/ike/IkeSessionParams.java
+++ b/src/java/android/net/ipsec/ike/IkeSessionParams.java
@@ -1732,11 +1732,13 @@
* Sets the retransmission timeout list in milliseconds.
*
* <p>Configures the retransmission by providing an array of relative retransmission
- * timeouts in milliseconds, where each timeout is the waiting time before next retry,
- * except the last timeout is the waiting time before terminating the IKE Session. Each
- * element in the array MUST be a value from 500 ms to 1800000 ms (30 minutes). The length
- * of the array MUST NOT exceed 10. This retransmission timeout list defaults to {0.5s, 1s,
- * 2s, 4s, 8s}
+ * timeouts in milliseconds. After sending out a request and before receiving the response,
+ * the IKE Session will iterate through the array and wait for the relative timeout before
+ * the next retry. If the last timeout is exceeded, the IKE Session will be terminated.
+ *
+ * <p>Each element in the array MUST be a value from 500 ms to 1800000 ms (30 minutes). The
+ * length of the array MUST NOT exceed 10. This retransmission timeout list defaults to
+ * {0.5s, 1s, 2s, 4s, 8s}
*
* @param retransTimeoutMillisList the array of relative retransmission timeout in
* milliseconds.
