Add javadoc comment around PeerConnection.dispose.

webrtc/sdk/android/api/org/webrtc/PeerConnection.java

 /*
  *  Copyright 2013 The WebRTC project authors. All Rights Reserved.
  *
  *  Use of this source code is governed by a BSD-style license
  *  that can be found in the LICENSE file in the root of the source
  *  tree. An additional intellectual property rights grant can be found
  *  in the file PATENTS.  All contributing project authors may
  *  be found in the AUTHORS file in the root of the source tree.
  */
 
@@ skipping 471 matching lines @@
   // TODO(fischman): add support for DTMF-related methods once that API
   // stabilizes.
   public native SignalingState signalingState();
 
   public native IceConnectionState iceConnectionState();
 
   public native IceGatheringState iceGatheringState();
 
   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) {
       nativeRemoveLocalStream(stream.nativeStream);
       stream.dispose();
     }
     localStreams.clear();
     for (RtpSender sender : senders) {
       sender.dispose();
     }
@@ skipping 26 matching lines @@
   private native RtpSender nativeCreateSender(String kind, String stream_id);
 
   private native List<RtpSender> nativeGetSenders();
 
   private native List<RtpReceiver> nativeGetReceivers();
 
   private native boolean nativeStartRtcEventLog(int file_descriptor, int max_size_bytes);
 
   private native void nativeStopRtcEventLog();
 }