From 43697f6da56c0c6eca8967a4fef57beb589d8990 Mon Sep 17 00:00:00 2001
From: deadbeef <deadbeef@webrtc.org>
Date: Tue, 12 Sep 2017 10:52:14 -0700
Subject: [PATCH] Add javadoc comment for PeerConnection.dispose.

Specifically calling out issue 3721 ("dispose can't be called from a
callback"), which developers frequently run into.

BUG=webrtc:3721
NOTRY=True

Review-Url: https://codereview.webrtc.org/3013573002
Cr-Commit-Position: refs/heads/master@{#19804}
---
 .../android/api/org/webrtc/PeerConnection.java   | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/webrtc/sdk/android/api/org/webrtc/PeerConnection.java b/webrtc/sdk/android/api/org/webrtc/PeerConnection.java
index f98b2e4b67..9ddfdfdc06 100644
--- a/webrtc/sdk/android/api/org/webrtc/PeerConnection.java
+++ b/webrtc/sdk/android/api/org/webrtc/PeerConnection.java
@@ -489,6 +489,22 @@ public class PeerConnection {
 
   public native void close();
 
+  /**
+   * Free native resources associated with this PeerConnection instance.
+   * <p>
+   * This method removes a reference count from the C++ PeerConnection object,
+   * which should result in it being destroyed. It also calls equivalent
+   * "dispose" methods on the Java objects attached to this PeerConnection
+   * (streams, senders, receivers), such that their associated C++ objects
+   * will also be destroyed.
+   * <p>
+   * Note that this method cannot be safely called from an observer callback
+   * (PeerConnection.Observer, DataChannel.Observer, etc.). If you want to, for
+   * example, destroy the PeerConnection after an "ICE failed" callback, you
+   * must do this asynchronously (in other words, unwind the stack first). See
+   * <a href="https://bugs.chromium.org/p/webrtc/issues/detail?id=3721">bug
+   * 3721</a> for more details.
+   */
   public void dispose() {
     close();
     for (MediaStream stream : localStreams) {