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-Original-Commit-Position: refs/heads/master@{#19804}
Cr-Mirrored-From: https://chromium.googlesource.com/external/webrtc
Cr-Mirrored-Commit: 43697f6da56c0c6eca8967a4fef57beb589d8990
diff --git a/sdk/android/api/org/webrtc/PeerConnection.java b/sdk/android/api/org/webrtc/PeerConnection.java
index f98b2e4..9ddfdfd 100644
--- a/sdk/android/api/org/webrtc/PeerConnection.java
+++ b/sdk/android/api/org/webrtc/PeerConnection.java
@@ -489,6 +489,22 @@
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) {
