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

webrtc/api/peerconnectioninterface.h

 /*
  *  Copyright 2012 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.
  */
 
 // 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_
 
 #include <memory>
 #include <ostream>
 #include <string>
 #include <utility>
 #include <vector>
 
@@ skipping 274 matching lines @@
     }
     void set_prerenderer_smoothing(bool enable) {
       media_config.video.disable_prerenderer_smoothing = !enable;
     }
 
     static const int kUndefined = -1;
     // Default maximum number of packets in the audio jitter buffer.
     static const int kAudioJitterBufferMaxPackets = 50;
     // ICE connection receiving timeout for aggressive configuration.
     static const int kAggressiveIceConnectionReceivingTimeout = 1000;
+
+    ////////////////////////////////////////////////////////////////////////
+    // 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;
-    // TODO(pthatcher): Rename this ice_servers, but update Chromium
-    // at the same time.
-    IceServers servers;
     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;
 
     // 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;
 
     RTCOfferAnswerOptions(int offer_to_receive_video,
                           int offer_to_receive_audio,
                           bool voice_activity_detection,
                           bool ice_restart,
                           bool use_rtp_mux)
         : offer_to_receive_video(offer_to_receive_video),
@@ skipping 16 matching lines @@
   virtual rtc::scoped_refptr<StreamCollectionInterface>
       local_streams() = 0;
 
   // Accessor methods to remote streams.
   virtual rtc::scoped_refptr<StreamCollectionInterface>
       remote_streams() = 0;
 
   // 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(
       MediaStreamTrackInterface* track,
       std::vector<MediaStreamInterface*> streams) {
     return nullptr;
   }
 
   // Remove an RtpSender from this PeerConnection.
   // Returns true on success.
   virtual bool RemoveTrack(RtpSenderInterface* sender) {
     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(
       const std::string& kind,
       const std::string& stream_id) {
     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>>();
   }
 
   virtual bool GetStats(StatsObserver* observer,
                         MediaStreamTrackInterface* track,
                         StatsOutputLevel level) = 0;
   // Gets stats using the new stats collection API, see webrtc/api/stats/. These
   // will replace old stats collection API when the new API has matured enough.
   // TODO(hbos): Default implementation that does nothing only exists as to not
   // break third party projects. As soon as they have been updated this should
   // 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 {
     return nullptr;
   }
   virtual const SessionDescriptionInterface* current_remote_description()
       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".
   virtual const SessionDescriptionInterface* pending_local_description() const {
     return nullptr;
   }
   virtual const SessionDescriptionInterface* pending_remote_description()
       const {
     return nullptr;
   }
@@ skipping 21 matching lines @@
   // Sets the local session description.
   // JsepInterface takes the ownership of |desc| even if it fails.
   // The |observer| callback will be called when done.
   virtual void SetLocalDescription(SetSessionDescriptionObserver* observer,
                                    SessionDescriptionInterface* desc) = 0;
   // Sets the remote session description.
   // JsepInterface takes the ownership of |desc| even if it fails.
   // 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() {
     return PeerConnectionInterface::RTCConfiguration();
   }
 
   // Sets the PeerConnection's global configuration to |config|.
   //
   // The members of |config| that may be changed are |type|, |servers|,
   // |ice_candidate_pool_size| and |prune_turn_ports| (though the candidate
@@ skipping 20 matching lines @@
       const PeerConnectionInterface::RTCConfiguration& config,
       RTCError* error) {
     return false;
   }
   // Version without error output param for backwards compatibility.
   // TODO(deadbeef): Remove once chromium is updated.
   virtual bool SetConfiguration(
       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.
   virtual SignalingState signaling_state() = 0;
   virtual IceConnectionState ice_connection_state() = 0;
   virtual IceGatheringState ice_gathering_state() = 0;
 
   // Starts RtcEventLog using existing file. Takes ownership of |file| and
   // passes it on to Call, which will take the ownership. If the
   // operation fails the file will be closed. The logging will stop
   // automatically after 10 minutes have passed, or when the StopRtcEventLog
   // function is called.
   // TODO(ivoc): Make this pure virtual when Chrome is updated.
   virtual bool StartRtcEventLog(rtc::PlatformFile file,
                                 int64_t max_size_bytes) {
     return false;
   }
 
   // Stops logging the RtcEventLog.
   // 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:
   // Dtor protected as objects shouldn't be deleted via this interface.
   ~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 {
     kSignalingState,
     kIceState,
   };
 
   // Triggered when the SignalingState changed.
   virtual void OnSignalingChange(
       PeerConnectionInterface::SignalingState new_state) = 0;
@@ skipping 17 matching lines @@
   virtual void OnDataChannel(
       rtc::scoped_refptr<DataChannelInterface> data_channel) {}
   // Deprecated; please use the version that uses a scoped_refptr.
   virtual void OnDataChannel(DataChannelInterface* data_channel) {}
 
   // Triggered when renegotiation is needed. For example, an ICE restart
   // has begun.
   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;
 
   // Called any time the IceGatheringState changes.
   virtual void OnIceGatheringChange(
       PeerConnectionInterface::IceGatheringState new_state) = 0;
 
   // A new ICE candidate has been gathered.
   virtual void OnIceCandidate(const IceCandidateInterface* candidate) = 0;
 
@@ skipping 11 matching lines @@
   // implement it.
   virtual void OnAddTrack(
       rtc::scoped_refptr<RtpReceiverInterface> receiver,
       const std::vector<rtc::scoped_refptr<MediaStreamInterface>>& streams) {}
 
  protected:
   // Dtor protected as objects shouldn't be deleted via this interface.
   ~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;
   };
 
   virtual void SetOptions(const Options& options) = 0;
 
   virtual rtc::scoped_refptr<PeerConnectionInterface> CreatePeerConnection(
       const PeerConnectionInterface::RTCConfiguration& configuration,
+      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;
-
-  virtual rtc::scoped_refptr<PeerConnectionInterface> CreatePeerConnection(
-      const PeerConnectionInterface::RTCConfiguration& configuration,
-      std::unique_ptr<cricket::PortAllocator> allocator,
-      std::unique_ptr<rtc::RTCCertificateGeneratorInterface> cert_generator,
-      PeerConnectionObserver* observer) = 0;
 
   virtual rtc::scoped_refptr<MediaStreamInterface>
       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.
   // Can use CopyConstraintsIntoAudioOptions to bridge the gap.
   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,
       const MediaConstraintsInterface* constraints) = 0;
 
   // Creates a new local VideoTrack. The same |source| can be used in several
   // tracks.
   virtual rtc::scoped_refptr<VideoTrackInterface> CreateVideoTrack(
       const std::string& label,
       VideoTrackSourceInterface* source) = 0;
@@ skipping 62 matching lines @@
 // Deprecated variant of the above.
 // TODO(kwiberg): Remove.
 rtc::scoped_refptr<PeerConnectionFactoryInterface>
 CreatePeerConnectionFactory();
 
 // Create a new instance of PeerConnectionFactoryInterface.
 //
 // |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,
     rtc::Thread* signaling_thread,
     AudioDeviceModule* default_adm,
     rtc::scoped_refptr<AudioEncoderFactory> audio_encoder_factory,
     rtc::scoped_refptr<AudioDecoderFactory> audio_decoder_factory,
     cricket::WebRtcVideoEncoderFactory* video_encoder_factory,
     cricket::WebRtcVideoDecoderFactory* video_decoder_factory);
 
@@ skipping 62 matching lines @@
     cricket::WebRtcVideoEncoderFactory* encoder_factory,
     cricket::WebRtcVideoDecoderFactory* decoder_factory) {
   return CreatePeerConnectionFactory(
       worker_and_network_thread, worker_and_network_thread, signaling_thread,
       default_adm, encoder_factory, decoder_factory);
 }
 
 }  // namespace webrtc
 
 #endif  // WEBRTC_API_PEERCONNECTIONINTERFACE_H_