update docs for Connection#onHold()

The topic adds a transactional way to verify call state changes.
Connection#onHold can now lead to the call being disconnected if the
Connection#setOnHold is not called within the 2 second timeframe. The
docs should be updated to reflect this behavior change.

Test: build + existing Telecom test suite
Fixes: b/267234374
Change-Id: I910843d4e8adec8d38cd32915f223540cefb9ac6

1 files changed, 5 insertions, 1 deletions

diff --git a/telecomm/java/android/telecom/Connection.java b/telecomm/java/android/telecom/Connection.java
index 943d8d6cdd55..4a541da9e5aa 100644
--- a/telecomm/java/android/telecom/Connection.java
+++ b/telecomm/java/android/telecom/Connection.java
@@ -3388,7 +3388,11 @@ public abstract class Connection extends Conferenceable {
     public void onAbort() {}
 
     /**
-     * Notifies this Connection of a request to hold.
+     * Notifies this Connection of a request to hold. {@link Connection#setOnHold} should be within
+     * the onHold() body in order to transition the call state to {@link Connection#STATE_HOLDING}.
+     * <p>
+     * Note: If the Connection does not transition to  {@link Connection#STATE_HOLDING} within 2
+     * seconds, the call will be disconnected.
      */
     public void onHold() {}