Adding more comments to every header file in api/ subdirectory.

webrtc/api/peerconnectioninterface.h

Index: webrtc/api/peerconnectioninterface.h
diff --git a/webrtc/api/peerconnectioninterface.h b/webrtc/api/peerconnectioninterface.h
index 6cc8be7112b691f03409d06e0cdf4f4e4f913562..ea94f504423e15c4841ad7feadcab770bbb6e3d9 100644
--- a/webrtc/api/peerconnectioninterface.h
+++ b/webrtc/api/peerconnectioninterface.h
@@ -10,43 +10,59 @@
 
 // This file contains the PeerConnection interface as defined in
 // http://dev.w3.org/2011/webrtc/editor/webrtc.html#peer-to-peer-connections.
-// Applications must use this interface to implement peerconnection.
-// PeerConnectionFactory class provides factory methods to create
-// peerconnection, mediastream and media tracks objects.
 //
-// The Following steps are needed to setup a typical call using Jsep.
+// The PeerConnectionFactory class provides factory methods to create
+// PeerConnection, MediaStream and MediaStreamTrack objects.
+//
+// The following steps are needed to setup a typical call using WebRTC:
+//
 // 1. Create a PeerConnectionFactoryInterface. Check constructors for more
 // information about input parameters.
-// 2. Create a PeerConnection object. Provide a configuration string which
-// points either to stun or turn server to generate ICE candidates and provide
-// an object that implements the PeerConnectionObserver interface.
-// 3. Create local MediaStream and MediaTracks using the PeerConnectionFactory
-// and add it to PeerConnection by calling AddStream.
-// 4. Create an offer and serialize it and send it to the remote peer.
-// 5. Once an ice candidate have been found PeerConnection will call the
+//
+// 2. Create a PeerConnection object. Provide a configuration struct which
+// points to STUN and/or TURN servers used to generate ICE candidates, and
+// provide an object that implements the PeerConnectionObserver interface,
+// which is used to receive callbacks from the PeerConnection.
+//
+// 3. Create local MediaStreamTracks using the PeerConnectionFactory and add
+// them to PeerConnection by calling AddTrack (or legacy method, AddStream).
+//
+// 4. Create an offer, call SetLocalDescription with it, serialize it, and send
+// it to the remote peer
+//
+// 5. Once an ICE candidate has been gathered, the PeerConnection will call the
 // observer function OnIceCandidate. The candidates must also be serialized and
 // sent to the remote peer.
+//
 // 6. Once an answer is received from the remote peer, call
-// SetLocalSessionDescription with the offer and SetRemoteSessionDescription
-// with the remote answer.
+// SetRemoteDescription with the remote answer.
+//
 // 7. Once a remote candidate is received from the remote peer, provide it to
-// the peerconnection by calling AddIceCandidate.
-
-
-// The Receiver of a call can decide to accept or reject the call.
-// This decision will be taken by the application not peerconnection.
-// If application decides to accept the call
+// the PeerConnection by calling AddIceCandidate.
+//
+// The receiver of a call (assuming the application is "call"-based) can decide
+// to accept or reject the call; this decision will be taken by the application,
+// not the PeerConnection.
+//
+// If the application decides to accept the call, it should:
+//
 // 1. Create PeerConnectionFactoryInterface if it doesn't exist.
+//
 // 2. Create a new PeerConnection.
+//
 // 3. Provide the remote offer to the new PeerConnection object by calling
-// SetRemoteSessionDescription.
+// SetRemoteDescription.
+//
 // 4. Generate an answer to the remote offer by calling CreateAnswer and send it
 // back to the remote peer.
+//
 // 5. Provide the local answer to the new PeerConnection by calling
-// SetLocalSessionDescription with the answer.
-// 6. Provide the remote ice candidates by calling AddIceCandidate.
-// 7. Once a candidate have been found PeerConnection will call the observer
-// function OnIceCandidate. Send these candidates to the remote peer.
+// SetLocalDescription with the answer.
+//
+// 6. Provide the remote ICE candidates by calling AddIceCandidate.
+//
+// 7. Once a candidate has been gathered, the PeerConnection will call the
+// observer function OnIceCandidate. Send these candidates to the remote peer.
 
 #ifndef WEBRTC_API_PEERCONNECTIONINTERFACE_H_
 #define WEBRTC_API_PEERCONNECTIONINTERFACE_H_
@@ -341,53 +357,143 @@ class PeerConnectionInterface : public rtc::RefCountInterface {
     static const int kAudioJitterBufferMaxPackets = 50;
     // ICE connection receiving timeout for aggressive configuration.
     static const int kAggressiveIceConnectionReceivingTimeout = 1000;
-    // TODO(pthatcher): Rename this ice_transport_type, but update
-    // Chromium at the same time.
-    IceTransportsType type = kAll;
+
+    ////////////////////////////////////////////////////////////////////////
+    // The below few fields mirror the standard RTCConfiguration dictionary:
+    // https://www.w3.org/TR/webrtc/#rtcconfiguration-dictionary
+    ////////////////////////////////////////////////////////////////////////
+
     // TODO(pthatcher): Rename this ice_servers, but update Chromium
     // at the same time.
     IceServers servers;
+    // TODO(pthatcher): Rename this ice_transport_type, but update
+    // Chromium at the same time.
+    IceTransportsType type = kAll;
     BundlePolicy bundle_policy = kBundlePolicyBalanced;
     RtcpMuxPolicy rtcp_mux_policy = kRtcpMuxPolicyRequire;
+    std::vector<rtc::scoped_refptr<rtc::RTCCertificate>> certificates;
+    int ice_candidate_pool_size = 0;
+
+    //////////////////////////////////////////////////////////////////////////
+    // The below fields correspond to constraints from the deprecated
+    // constraints interface for constructing a PeerConnection.
+    //
+    // rtc::Optional fields can be "missing", in which case the implementation
+    // default will be used.
+    //////////////////////////////////////////////////////////////////////////
+
+    // If set to true, don't gather IPv6 ICE candidates.
+    // TODO(deadbeef): Remove this? IPv6 support has long stopped being
+    // experimental
+    bool disable_ipv6 = false;
+
+    // If set to true, use RTP data channels instead of SCTP.
+    // TODO(deadbeef): Remove this. We no longer commit to supporting RTP data
+    // channels, though some applications are still working on moving off of
+    // them.
+    bool enable_rtp_data_channel = false;
+
+    // Minimum bitrate at which screencast video tracks will be encoded at.
+    // This means adding padding bits up to this bitrate, which can help
+    // when switching from a static scene to one with motion.
+    rtc::Optional<int> screencast_min_bitrate;
+
+    // Use new combined audio/video bandwidth estimation?
+    rtc::Optional<bool> combined_audio_video_bwe;
+
+    // Can be used to disable DTLS-SRTP. This should never be done, but can be
+    // useful for testing purposes, for example in setting up a loopback call
+    // with a single PeerConnection.
+    rtc::Optional<bool> enable_dtls_srtp;
+
+    /////////////////////////////////////////////////
+    // The below fields are not part of the standard.
+    /////////////////////////////////////////////////
+
+    // Can be used to disable TCP candidate generation.
     TcpCandidatePolicy tcp_candidate_policy = kTcpCandidatePolicyEnabled;
+
+    // Can be used to avoid gathering candidates for a "higher cost" network,
+    // if a lower cost one exists. For example, if both Wi-Fi and cellular
+    // interfaces are available, this could be used to avoid using the cellular
+    // interface.
     CandidateNetworkPolicy candidate_network_policy =
         kCandidateNetworkPolicyAll;
+
+    // The maximum number of packets that can be stored in the NetEq audio
+    // jitter buffer. Can be reduced to lower tolerated audio latency.
     int audio_jitter_buffer_max_packets = kAudioJitterBufferMaxPackets;
+
+    // Whether to use the NetEq "fast mode" which will accelerate audio quicker
+    // if it falls behind.
     bool audio_jitter_buffer_fast_accelerate = false;
-    int ice_connection_receiving_timeout = kUndefined;         // ms
-    int ice_backup_candidate_pair_ping_interval = kUndefined;  // ms
+
+    // Timeout in milliseconds before an ICE candidate pair is considered to be
+    // "not receiving", after which a lower priority candidate pair may be
+    // selected.
+    int ice_connection_receiving_timeout = kUndefined;
+
+    // Interval in milliseconds at which an ICE "backup" candidate pair will be
+    // pinged. This is a candidate pair which is not actively in use, but may
+    // be switched to if the active candidate pair becomes unusable.
+    //
+    // This is relevant mainly to Wi-Fi/cell handoff; the application may not
+    // want this backup cellular candidate pair pinged frequently, since it
+    // consumes data/battery.
+    int ice_backup_candidate_pair_ping_interval = kUndefined;
+
+    // Can be used to enable continual gathering, which means new candidates
+    // will be gathered as network interfaces change. Note that if continual
+    // gathering is used, the candidate removal API should also be used, to
+    // avoid an ever-growing list of candidates.
     ContinualGatheringPolicy continual_gathering_policy = GATHER_ONCE;
-    std::vector<rtc::scoped_refptr<rtc::RTCCertificate>> certificates;
+
+    // If set to true, candidate pairs will be pinged in order of most likely
+    // to work (which means using a TURN server, generally), rather than in
+    // standard priority order.
     bool prioritize_most_likely_ice_candidate_pairs = false;
+
     struct cricket::MediaConfig media_config;
-    // Flags corresponding to values set by constraint flags.
-    // rtc::Optional flags can be "missing", in which case the webrtc
-    // default applies.
-    bool disable_ipv6 = false;
-    bool enable_rtp_data_channel = false;
+
+    // This doesn't currently work. For a while we were working on adding QUIC
+    // data channel support to PeerConnection, but decided on a different
+    // approach, and that code hasn't been updated for a while.
     bool enable_quic = false;
-    rtc::Optional<int> screencast_min_bitrate;
-    rtc::Optional<bool> combined_audio_video_bwe;
-    rtc::Optional<bool> enable_dtls_srtp;
-    int ice_candidate_pool_size = 0;
+
+    // If set to true, only one preferred TURN allocation will be used per
+    // network interface. UDP is preferred over TCP and IPv6 over IPv4. This
+    // can be used to cut down on the number of candidate pairings.
     bool prune_turn_ports = false;
+
     // If set to true, this means the ICE transport should presume TURN-to-TURN
     // candidate pairs will succeed, even before a binding response is received.
+    // This can be used to optimize the initial connection time, since the DTLS
+    // handshake can begin immediately.
     bool presume_writable_when_fully_relayed = false;
+
     // If true, "renomination" will be added to the ice options in the transport
     // description.
+    // See: https://tools.ietf.org/html/draft-thatcher-ice-renomination-00
     bool enable_ice_renomination = false;
-    // If true, ICE role is redetermined when peerconnection sets a local
-    // transport description that indicates an ICE restart.
+
+    // If true, the ICE role is re-determined when the PeerConnection sets a
+    // local transport description that indicates an ICE restart.
+    //
+    // This is standard RFC5245 ICE behavior, but causes unnecessary role
+    // thrashing, so an application may wish to avoid it. This role
+    // re-determining was removed in ICEbis (ICE v2).
     bool redetermine_role_on_ice_restart = true;
+
     // If set, the min interval (max rate) at which we will send ICE checks
     // (STUN pings), in milliseconds.
     rtc::Optional<int> ice_check_min_interval;
+
     //
     // Don't forget to update operator== if adding something.
     //
   };
 
+  // See: https://www.w3.org/TR/webrtc/#idl-def-rtcofferansweroptions
   struct RTCOfferAnswerOptions {
     static const int kUndefined = -1;
     static const int kMaxOfferToReceiveMedia = 1;
@@ -395,10 +501,23 @@ class PeerConnectionInterface : public rtc::RefCountInterface {
     // The default value for constraint offerToReceiveX:true.
     static const int kOfferToReceiveMediaTrue = 1;
 
+    // These have been removed from the standard in favor of the "transceiver"
+    // API, but given that we don't support that API, we still have them here.
+    //
+    // offer_to_receive_X set to 1 will cause a media description to be
+    // generated in the offer, even if no tracks of that type have been added.
+    // Values greater than 1 are treated the same.
+    //
+    // If set to 0, the generated directional attribute will not include the
+    // "recv" direction (meaning it will be "sendonly" or "inactive".
     int offer_to_receive_video = kUndefined;
     int offer_to_receive_audio = kUndefined;
+
     bool voice_activity_detection = true;
     bool ice_restart = false;
+
+    // If true, will offer to BUNDLE audio/video/data together. Not to be
+    // confused with RTCP mux (multiplexing RTP and RTCP together).
     bool use_rtp_mux = true;
 
     RTCOfferAnswerOptions() = default;
@@ -435,16 +554,25 @@ class PeerConnectionInterface : public rtc::RefCountInterface {
   // Add a new MediaStream to be sent on this PeerConnection.
   // Note that a SessionDescription negotiation is needed before the
   // remote peer can receive the stream.
+  //
+  // This has been removed from the standard in favor of a track-based API. So,
+  // this is equivalent to simply calling AddTrack for each track within the
+  // stream, with the one difference that if "stream->AddTrack(...)" is called
+  // later, the PeerConnection will automatically pick up the new track. Though
+  // this functionality will be deprecated in the future.
   virtual bool AddStream(MediaStreamInterface* stream) = 0;
 
   // Remove a MediaStream from this PeerConnection.
-  // Note that a SessionDescription negotiation is need before the
+  // Note that a SessionDescription negotiation is needed before the
   // remote peer is notified.
   virtual void RemoveStream(MediaStreamInterface* stream) = 0;
 
   // TODO(deadbeef): Make the following two methods pure virtual once
   // implemented by all subclasses of PeerConnectionInterface.
-  // Add a new MediaStreamTrack to be sent on this PeerConnection.
+
+  // Add a new MediaStreamTrack to be sent on this PeerConnection, and return
+  // the newly created RtpSender.
+  //
   // |streams| indicates which stream labels the track should be associated
   // with.
   virtual rtc::scoped_refptr<RtpSenderInterface> AddTrack(
@@ -459,13 +587,25 @@ class PeerConnectionInterface : public rtc::RefCountInterface {
     return false;
   }
 
-  // Returns pointer to the created DtmfSender on success.
-  // Otherwise returns NULL.
+  // Returns pointer to a DtmfSender on success. Otherwise returns NULL.
+  //
+  // This API is no longer part of the standard; instead DtmfSenders are
+  // obtained from RtpSenders. Which is what the implementation does; it finds
+  // an RtpSender for |track| and just returns its DtmfSender.
   virtual rtc::scoped_refptr<DtmfSenderInterface> CreateDtmfSender(
       AudioTrackInterface* track) = 0;
 
   // TODO(deadbeef): Make these pure virtual once all subclasses implement them.
+
+  // Creates a sender without a track. Can be used for "early media"/"warmup"
+  // use cases, where the application may want to negotiate video attributes
+  // before a track is available to send.
+  //
+  // The standard way to do this would be through "addTransceiver", but we
+  // don't support that API yet.
+  //
   // |kind| must be "audio" or "video".
+  //
   // |stream_id| is used to populate the msid attribute; if empty, one will
   // be generated automatically.
   virtual rtc::scoped_refptr<RtpSenderInterface> CreateSender(
@@ -474,11 +614,23 @@ class PeerConnectionInterface : public rtc::RefCountInterface {
     return rtc::scoped_refptr<RtpSenderInterface>();
   }
 
+  // Get all RtpSenders, created either through AddStream, AddTrack, or
+  // CreateSender. Note that these are "Plan B SDP" RtpSenders, not "Unified
+  // Plan SDP" RtpSenders, which means that all senders of a specific media
+  // type share the same media description.
   virtual std::vector<rtc::scoped_refptr<RtpSenderInterface>> GetSenders()
       const {
     return std::vector<rtc::scoped_refptr<RtpSenderInterface>>();
   }
 
+  // Get all RtpReceivers, created when a remote description is applied.
+  // Note that these are "Plan B SDP" RtpReceivers, not "Unified Plan SDP"
+  // RtpReceivers, which means that all receivers of a specific media type
+  // share the same media description.
+  //
+  // It is also possible to have a media description with no associated
+  // RtpReceivers, if the directional attribute does not indicate that the
+  // remote peer is sending any media.
   virtual std::vector<rtc::scoped_refptr<RtpReceiverInterface>> GetReceivers()
       const {
     return std::vector<rtc::scoped_refptr<RtpReceiverInterface>>();
@@ -494,12 +646,22 @@ class PeerConnectionInterface : public rtc::RefCountInterface {
   // be changed to "= 0;".
   virtual void GetStats(RTCStatsCollectorCallback* callback) {}
 
+  // Create a data channel with the provided config, or default config if none
+  // is provided. Note that an offer/answer negotiation is still necessary
+  // before the data channel can be used.
+  //
+  // Also, calling CreateDataChannel is the only way to get a data "m=" section
+  // in SDP, so it should be done before CreateOffer is called, if the
+  // application plans to use data channels.
   virtual rtc::scoped_refptr<DataChannelInterface> CreateDataChannel(
       const std::string& label,
       const DataChannelInit* config) = 0;
 
+  // Returns the more recently applied description; "pending" if it exists, and
+  // otherwise "current". See below.
   virtual const SessionDescriptionInterface* local_description() const = 0;
   virtual const SessionDescriptionInterface* remote_description() const = 0;
+
   // A "current" description the one currently negotiated from a complete
   // offer/answer exchange.
   virtual const SessionDescriptionInterface* current_local_description() const {
@@ -509,6 +671,7 @@ class PeerConnectionInterface : public rtc::RefCountInterface {
       const {
     return nullptr;
   }
+
   // A "pending" description is one that's part of an incomplete offer/answer
   // exchange (thus, either an offer or a pranswer). Once the offer/answer
   // exchange is finished, the "pending" description will become "current".
@@ -550,14 +713,14 @@ class PeerConnectionInterface : public rtc::RefCountInterface {
   // The |observer| callback will be called when done.
   virtual void SetRemoteDescription(SetSessionDescriptionObserver* observer,
                                     SessionDescriptionInterface* desc) = 0;
-  // Restarts or updates the ICE Agent process of gathering local candidates
-  // and pinging remote candidates.
+  // Deprecated; Replaced by SetConfiguration.
   // TODO(deadbeef): Remove once Chrome is moved over to SetConfiguration.
   virtual bool UpdateIce(const IceServers& configuration,
                          const MediaConstraintsInterface* constraints) {
     return false;
   }
   virtual bool UpdateIce(const IceServers& configuration) { return false; }
+
   // TODO(deadbeef): Make this pure virtual once all Chrome subclasses of
   // PeerConnectionInterface implement it.
   virtual PeerConnectionInterface::RTCConfiguration GetConfiguration() {
@@ -598,20 +761,25 @@ class PeerConnectionInterface : public rtc::RefCountInterface {
       const PeerConnectionInterface::RTCConfiguration& config) {
     return false;
   }
+
   // Provides a remote candidate to the ICE Agent.
   // A copy of the |candidate| will be created and added to the remote
   // description. So the caller of this method still has the ownership of the
   // |candidate|.
-  // TODO(ronghuawu): Consider to change this so that the AddIceCandidate will
-  // take the ownership of the |candidate|.
   virtual bool AddIceCandidate(const IceCandidateInterface* candidate) = 0;
 
-  // Removes a group of remote candidates from the ICE agent.
+  // Removes a group of remote candidates from the ICE agent. Needed mainly for
+  // continual gathering, to avoid an ever-growing list of candidates as
+  // networks come and go.
   virtual bool RemoveIceCandidates(
       const std::vector<cricket::Candidate>& candidates) {
     return false;
   }
 
+  // Register a metric observer (used by chromium).
+  //
+  // There can only be one observer at a time. Before the observer is
+  // destroyed, RegisterUMAOberver(nullptr) should be called.
   virtual void RegisterUMAObserver(UMAObserver* observer) = 0;
 
   // Returns the current SignalingState.
@@ -634,7 +802,8 @@ class PeerConnectionInterface : public rtc::RefCountInterface {
   // TODO(ivoc): Make this pure virtual when Chrome is updated.
   virtual void StopRtcEventLog() {}
 
-  // Terminates all media and closes the transport.
+  // Terminates all media, closes the transports, and in general releases any
+  // resources used by the PeerConnection. This is an irreversible operation.
   virtual void Close() = 0;
 
  protected:
@@ -642,8 +811,8 @@ class PeerConnectionInterface : public rtc::RefCountInterface {
   ~PeerConnectionInterface() {}
 };
 
-// PeerConnection callback interface. Application should implement these
-// methods.
+// PeerConnection callback interface, used for RTCPeerConnection events.
+// Application should implement these methods.
 class PeerConnectionObserver {
  public:
   enum StateType {
@@ -681,6 +850,11 @@ class PeerConnectionObserver {
   virtual void OnRenegotiationNeeded() = 0;
 
   // Called any time the IceConnectionState changes.
+  //
+  // Note that our ICE states lag behind the standard slightly. The most
+  // notable differences include the fact that "failed" occurs after 15
+  // seconds, not 30, and this actually represents a combination ICE + DTLS
+  // state, so it may be "failed" if DTLS fails while ICE succeeds.
   virtual void OnIceConnectionChange(
       PeerConnectionInterface::IceConnectionState new_state) = 0;
 
@@ -712,39 +886,50 @@ class PeerConnectionObserver {
   ~PeerConnectionObserver() {}
 };
 
-// PeerConnectionFactoryInterface is the factory interface use for creating
-// PeerConnection, MediaStream and media tracks.
-// PeerConnectionFactoryInterface will create required libjingle threads,
-// socket and network manager factory classes for networking.
-// If an application decides to provide its own threads and network
-// implementation of these classes it should use the alternate
-// CreatePeerConnectionFactory method which accepts threads as input and use the
-// CreatePeerConnection version that takes a PortAllocator as an
-// argument.
+// PeerConnectionFactoryInterface is the factory interface used for creating
+// PeerConnection, MediaStream and MediaStreamTrack objects.
+//
+// The simplest method for obtaiing one, CreatePeerConnectionFactory will
+// create the required libjingle threads, socket and network manager factory
+// classes for networking if none are provided, though it requires that the
+// application runs a message loop on the thread that called the method (see
+// explanation below)
+//
+// If an application decides to provide its own threads and/or implementation
+// of networking classes, it should use the alternate
+// CreatePeerConnectionFactory method which accepts threads as input, and use
+// the CreatePeerConnection version that takes a PortAllocator as an argument.
 class PeerConnectionFactoryInterface : public rtc::RefCountInterface {
  public:
   class Options {
    public:
-    Options()
-        : disable_encryption(false),
-          disable_sctp_data_channels(false),
-          disable_network_monitor(false),
-          network_ignore_mask(rtc::kDefaultNetworkIgnoreMask),
-          ssl_max_version(rtc::SSL_PROTOCOL_DTLS_12),
-          crypto_options(rtc::CryptoOptions::NoGcm()) {}
-    bool disable_encryption;
-    bool disable_sctp_data_channels;
-    bool disable_network_monitor;
+    Options() : crypto_options(rtc::CryptoOptions::NoGcm()) {}
+
+    // If set to true, created PeerConnections won't enforce any SRTP
+    // requirement, allowing unsecured media. Should only be used for
+    // testing/debugging.
+    bool disable_encryption = false;
+
+    // Deprecated. The only effect of setting this to true is that
+    // CreateDataChannel will fail, which is not that useful.
+    bool disable_sctp_data_channels = false;
+
+    // If set to true, any platform-supported network monitoring capability
+    // won't be used, and instead networks will only be updated via polling.
+    //
+    // This only has an effect if a PeerConnection is created with the default
+    // PortAllocator implementation.
+    bool disable_network_monitor = false;
 
     // Sets the network types to ignore. For instance, calling this with
     // ADAPTER_TYPE_ETHERNET | ADAPTER_TYPE_LOOPBACK will ignore Ethernet and
     // loopback interfaces.
-    int network_ignore_mask;
+    int network_ignore_mask = rtc::kDefaultNetworkIgnoreMask;
 
     // Sets the maximum supported protocol version. The highest version
     // supported by both ends will be used for the connection, i.e. if one
     // party supports DTLS 1.0 and the other DTLS 1.2, DTLS 1.0 will be used.
-    rtc::SSLProtocolVersion ssl_max_version;
+    rtc::SSLProtocolVersion ssl_max_version = rtc::SSL_PROTOCOL_DTLS_12;
 
     // Sets crypto related options, e.g. enabled cipher suites.
     rtc::CryptoOptions crypto_options;
@@ -754,13 +939,15 @@ class PeerConnectionFactoryInterface : public rtc::RefCountInterface {
 
   virtual rtc::scoped_refptr<PeerConnectionInterface> CreatePeerConnection(
       const PeerConnectionInterface::RTCConfiguration& configuration,
-      const MediaConstraintsInterface* constraints,
       std::unique_ptr<cricket::PortAllocator> allocator,
       std::unique_ptr<rtc::RTCCertificateGeneratorInterface> cert_generator,
       PeerConnectionObserver* observer) = 0;
 
+  // Deprecated; should use RTCConfiguration for everything that previously
+  // used constraints.
   virtual rtc::scoped_refptr<PeerConnectionInterface> CreatePeerConnection(
       const PeerConnectionInterface::RTCConfiguration& configuration,
+      const MediaConstraintsInterface* constraints,
       std::unique_ptr<cricket::PortAllocator> allocator,
       std::unique_ptr<rtc::RTCCertificateGeneratorInterface> cert_generator,
       PeerConnectionObserver* observer) = 0;
@@ -769,7 +956,7 @@ class PeerConnectionFactoryInterface : public rtc::RefCountInterface {
       CreateLocalMediaStream(const std::string& label) = 0;
 
   // Creates a AudioSourceInterface.
-  // |constraints| decides audio processing settings but can be NULL.
+  // |options| decides audio processing settings.
   virtual rtc::scoped_refptr<AudioSourceInterface> CreateAudioSource(
       const cricket::AudioOptions& options) = 0;
   // Deprecated - use version above.
@@ -777,13 +964,14 @@ class PeerConnectionFactoryInterface : public rtc::RefCountInterface {
   virtual rtc::scoped_refptr<AudioSourceInterface> CreateAudioSource(
       const MediaConstraintsInterface* constraints) = 0;
 
-  // Creates a VideoTrackSourceInterface. The new source take ownership of
+  // Creates a VideoTrackSourceInterface. The new source takes ownership of
   // |capturer|.
+  // TODO(deadbeef): Switch to std::unique_ptr<>, to make this transfership of
+  // ownership more clear.
   virtual rtc::scoped_refptr<VideoTrackSourceInterface> CreateVideoSource(
       cricket::VideoCapturer* capturer) = 0;
   // A video source creator that allows selection of resolution and frame rate.
-  // |constraints| decides video resolution and frame rate but can
-  // be NULL.
+  // |constraints| decides video resolution and frame rate but can be NULL.
   // In the NULL case, use the version above.
   virtual rtc::scoped_refptr<VideoTrackSourceInterface> CreateVideoSource(
       cricket::VideoCapturer* capturer,
@@ -866,8 +1054,11 @@ CreatePeerConnectionFactory();
 // |network_thread|, |worker_thread| and |signaling_thread| are
 // the only mandatory parameters.
 //
-// If non-null, ownership of |default_adm|, |encoder_factory| and
-// |decoder_factory| are transferred to the returned factory.
+// If non-null, a reference is added to |default_adm|, and ownership of
+// |video_encoder_factory| and |video_decoder_factory| is transferred to the
+// returned factory.
+// TODO(deadbeef): Use rtc::scoped_refptr<> and std::unique_ptr<> to make this
+// ownership transfer and ref counting more obvious.
 rtc::scoped_refptr<PeerConnectionFactoryInterface> CreatePeerConnectionFactory(
     rtc::Thread* network_thread,
     rtc::Thread* worker_thread,