Adding comments explaining Java createSender and setTrack methods.

This has been a frequent source of confusion, especially since the
method names don't match anything in the standard exactly.

BUG=None
NOTRY=True

Review-Url: https://codereview.webrtc.org/2994733002
Cr-Commit-Position: refs/heads/master@{#19290}

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

@@ -286,6 +286,43 @@ public class PeerConnection {
     localStreams.remove(stream);
   }
 
+  /**
+   * Creates an RtpSender without a track.
+   * <p>
+   * This method allows an application to cause the PeerConnection to negotiate
+   * sending/receiving a specific media type, but without having a track to
+   * send yet.
+   * <p>
+   * When the application does want to begin sending a track, it can call
+   * RtpSender.setTrack, which doesn't require any additional SDP negotiation.
+   * <p>
+   * Example use:
+   * <pre>
+   * {@code
+   * audioSender = pc.createSender("audio", "stream1");
+   * videoSender = pc.createSender("video", "stream1");
+   * // Do normal SDP offer/answer, which will kick off ICE/DTLS and negotiate
+   * // media parameters....
+   * // Later, when the endpoint is ready to actually begin sending:
+   * audioSender.setTrack(audioTrack, false);
+   * videoSender.setTrack(videoTrack, false);
+   * }
+   * </pre>
+   * Note: This corresponds most closely to "addTransceiver" in the official
+   * WebRTC API, in that it creates a sender without a track. It was
+   * implemented before addTransceiver because it provides useful
+   * functionality, and properly implementing transceivers would have required
+   * a great deal more work.
+   *
+   * @param kind      Corresponds to MediaStreamTrack kinds (must be "audio" or
+   *                  "video").
+   * @param stream_id The ID of the MediaStream that this sender's track will
+   *                  be associated with when SDP is applied to the remote
+   *                  PeerConnection. If createSender is used to create an
+   *                  audio and video sender that should be synchronized, they
+   *                  should use the same stream ID.
+   * @return          A new RtpSender object if successful, or null otherwise.
+   */
   public RtpSender createSender(String kind, String stream_id) {
     RtpSender new_sender = nativeCreateSender(kind, stream_id);
     if (new_sender != null) {

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

@@ -29,11 +29,20 @@ public class RtpSender {
     dtmfSender = (nativeDtmfSender != 0) ? new DtmfSender(nativeDtmfSender) : null;
   }
 
-  // If |takeOwnership| is true, the RtpSender takes ownership of the track
+  /**
-  // from the caller, and will auto-dispose of it when no longer needed.
+   * Starts sending a new track, without requiring additional SDP negotiation.
-  // |takeOwnership| should only be used if the caller owns the track; it is
+   * <p>
-  // not appropriate when the track is owned by, for example, another RtpSender
+   * Note: This is equivalent to replaceTrack in the official WebRTC API. It
-  // or a MediaStream.
+   * was just implemented before the standards group settled on a name.
+   *
+   * @param takeOwnership If true, the RtpSender takes ownership of the track
+   *                      from the caller, and will auto-dispose of it when no
+   *                      longer needed. |takeOwnership| should only be used if
+   *                      the caller owns the track; it is not appropriate when
+   *                      the track is owned by, for example, another RtpSender
+   *                      or a MediaStream.
+   * @return              true on success and false on failure.
+   */
   public boolean setTrack(MediaStreamTrack track, boolean takeOwnership) {
     if (!nativeSetTrack(nativeRtpSender, (track == null) ? 0 : track.nativeTrack)) {
       return false;