diff --git a/webrtc/api/datachannelinterface.h b/webrtc/api/datachannelinterface.h
index 5fa657d..92bdee2 100644
--- a/webrtc/api/datachannelinterface.h
+++ b/webrtc/api/datachannelinterface.h
@@ -24,31 +24,43 @@
 
 namespace webrtc {
 
+// C++ version of: https://www.w3.org/TR/webrtc/#idl-def-rtcdatachannelinit
+// TODO(deadbeef): Use rtc::Optional for the "-1 if unset" things.
 struct DataChannelInit {
-  DataChannelInit()
-      : reliable(false),
-        ordered(true),
-        maxRetransmitTime(-1),
-        maxRetransmits(-1),
-        negotiated(false),
-        id(-1) {
-  }
+  // Deprecated. Reliability is assumed, and channel will be unreliable if
+  // maxRetransmitTime or MaxRetransmits is set.
+  bool reliable = false;
 
-  bool reliable;           // Deprecated.
-  bool ordered;            // True if ordered delivery is required.
-  int maxRetransmitTime;   // The max period of time in milliseconds in which
-                           // retransmissions will be sent.  After this time, no
-                           // more retransmissions will be sent. -1 if unset.
-  int maxRetransmits;      // The max number of retransmissions. -1 if unset.
-  std::string protocol;    // This is set by the application and opaque to the
-                           // WebRTC implementation.
-  bool negotiated;         // True if the channel has been externally negotiated
-                           // and we do not send an in-band signalling in the
-                           // form of an "open" message.
-  int id;                  // The stream id, or SID, for SCTP data channels. -1
-                           // if unset.
+  // True if ordered delivery is required.
+  bool ordered = true;
+
+  // The max period of time in milliseconds in which retransmissions will be
+  // sent. After this time, no more retransmissions will be sent. -1 if unset.
+  //
+  // Cannot be set along with |maxRetransmits|.
+  int maxRetransmitTime = -1;
+
+  // The max number of retransmissions. -1 if unset.
+  //
+  // Cannot be set along with |maxRetransmitTime|.
+  int maxRetransmits = -1;
+
+  // This is set by the application and opaque to the WebRTC implementation.
+  std::string protocol;
+
+  // True if the channel has been externally negotiated and we do not send an
+  // in-band signalling in the form of an "open" message. If this is true, |id|
+  // below must be set; otherwise it should be unset and will be negotiated
+  // in-band.
+  bool negotiated = false;
+
+  // The stream id, or SID, for SCTP data channels. -1 if unset (see above).
+  int id = -1;
 };
 
+// At the JavaScript level, data can be passed in as a string or a blob, so
+// this structure's |binary| flag tells whether the data should be interpreted
+// as binary or text.
 struct DataBuffer {
   DataBuffer(const rtc::CopyOnWriteBuffer& data, bool binary)
       : data(data),
@@ -68,6 +80,10 @@
   bool binary;
 };
 
+// Used to implement RTCDataChannel events.
+//
+// The code responding to these callbacks should unwind the stack before
+// using any other webrtc APIs; re-entrancy is not supported.
 class DataChannelObserver {
  public:
   // The data channel state have changed.
@@ -83,7 +99,8 @@
 
 class DataChannelInterface : public rtc::RefCountInterface {
  public:
-  // Keep in sync with DataChannel.java:State and
+  // C++ version of: https://www.w3.org/TR/webrtc/#idl-def-rtcdatachannelstate
+  // Unlikely to change, but keep in sync with DataChannel.java:State and
   // RTCDataChannel.h:RTCDataChannelState.
   enum DataState {
     kConnecting,
@@ -107,14 +124,20 @@
     return "";
   }
 
+  // Used to receive events from the data channel. Only one observer can be
+  // registered at a time. UnregisterObserver should be called before the
+  // observer object is destroyed.
   virtual void RegisterObserver(DataChannelObserver* observer) = 0;
   virtual void UnregisterObserver() = 0;
+
   // The label attribute represents a label that can be used to distinguish this
   // DataChannel object from other DataChannel objects.
   virtual std::string label() const = 0;
-  virtual bool reliable() const = 0;
 
-  // TODO(tommyw): Remove these dummy implementations when all classes have
+  // The accessors below simply return the properties from the DataChannelInit
+  // the data channel was constructed with.
+  virtual bool reliable() const = 0;
+  // TODO(deadbeef): Remove these dummy implementations when all classes have
   // implemented these APIs. They should all just return the values the
   // DataChannel was created with.
   virtual bool ordered() const { return false; }
@@ -123,18 +146,33 @@
   virtual std::string protocol() const { return std::string(); }
   virtual bool negotiated() const { return false; }
 
+  // Returns the ID from the DataChannelInit, if it was negotiated out-of-band.
+  // If negotiated in-band, this ID will be populated once the DTLS role is
+  // determined, and until then this will return -1.
   virtual int id() const = 0;
   virtual DataState state() const = 0;
   virtual uint32_t messages_sent() const = 0;
   virtual uint64_t bytes_sent() const = 0;
   virtual uint32_t messages_received() const = 0;
   virtual uint64_t bytes_received() const = 0;
-  // The buffered_amount returns the number of bytes of application data
-  // (UTF-8 text and binary data) that have been queued using SendBuffer but
-  // have not yet been transmitted to the network.
+
+  // Returns the number of bytes of application data (UTF-8 text and binary
+  // data) that have been queued using Send but have not yet been processed at
+  // the SCTP level. See comment above Send below.
   virtual uint64_t buffered_amount() const = 0;
+
+  // Begins the graceful data channel closing procedure. See:
+  // https://tools.ietf.org/html/draft-ietf-rtcweb-data-channel-13#section-6.7
   virtual void Close() = 0;
-  // Sends |data| to the remote peer.
+
+  // Sends |data| to the remote peer. If the data can't be sent at the SCTP
+  // level (due to congestion control), it's buffered at the data channel level,
+  // up to a maximum of 16MB. If Send is called while this buffer is full, the
+  // data channel will be closed abruptly.
+  //
+  // So, it's important to use buffered_amount() and OnBufferedAmountChange to
+  // ensure the data channel is used efficiently but without filling this
+  // buffer.
   virtual bool Send(const DataBuffer& buffer) = 0;
 
  protected:
diff --git a/webrtc/api/dtmfsenderinterface.h b/webrtc/api/dtmfsenderinterface.h
index a4d270d..a1ef3ec 100644
--- a/webrtc/api/dtmfsenderinterface.h
+++ b/webrtc/api/dtmfsenderinterface.h
@@ -16,12 +16,11 @@
 #include "webrtc/api/mediastreaminterface.h"
 #include "webrtc/base/refcount.h"
 
-// This file contains interfaces for DtmfSender.
-
 namespace webrtc {
 
-// DtmfSender callback interface. Application should implement this interface
-// to get notifications from the DtmfSender.
+// DtmfSender callback interface, used to implement RTCDtmfSender events.
+// Applications should implement this interface to get notifications from the
+// DtmfSender.
 class DtmfSenderObserverInterface {
  public:
   // Triggered when DTMF |tone| is sent.
@@ -35,13 +34,18 @@
 
 // The interface of native implementation of the RTCDTMFSender defined by the
 // WebRTC W3C Editor's Draft.
+// See: https://www.w3.org/TR/webrtc/#peer-to-peer-dtmf
 class DtmfSenderInterface : public rtc::RefCountInterface {
  public:
+  // Used to receive events from the DTMF sender. Only one observer can be
+  // registered at a time. UnregisterObserver should be called before the
+  // observer object is destroyed.
   virtual void RegisterObserver(DtmfSenderObserverInterface* observer) = 0;
   virtual void UnregisterObserver() = 0;
 
-  // Returns true if this DtmfSender is capable of sending DTMF.
-  // Otherwise returns false.
+  // Returns true if this DtmfSender is capable of sending DTMF. Otherwise
+  // returns false. To be able to send DTMF, the associated RtpSender must be
+  // able to send packets, and a "telephone-event" codec must be negotiated.
   virtual bool CanInsertDtmf() = 0;
 
   // Queues a task that sends the DTMF |tones|. The |tones| parameter is treated
@@ -49,20 +53,26 @@
   // * generate the associated DTMF tones. The characters a to d are equivalent
   // to A to D. The character ',' indicates a delay of 2 seconds before
   // processing the next character in the tones parameter.
+  //
   // Unrecognized characters are ignored.
+  //
   // The |duration| parameter indicates the duration in ms to use for each
-  // character passed in the |tones| parameter.
-  // The duration cannot be more than 6000 or less than 70.
-  // The |inter_tone_gap| parameter indicates the gap between tones in ms.
-  // The |inter_tone_gap| must be at least 50 ms but should be as short as
+  // character passed in the |tones| parameter. The duration cannot be more
+  // than 6000 or less than 70.
+  //
+  // The |inter_tone_gap| parameter indicates the gap between tones in ms. The
+  // |inter_tone_gap| must be at least 50 ms but should be as short as
   // possible.
+  //
   // If InsertDtmf is called on the same object while an existing task for this
   // object to generate DTMF is still running, the previous task is canceled.
   // Returns true on success and false on failure.
   virtual bool InsertDtmf(const std::string& tones, int duration,
                           int inter_tone_gap) = 0;
 
-  // Returns the track given as argument to the constructor.
+  // Returns the track given as argument to the constructor. Only exists for
+  // backwards compatibilty; now that DtmfSenders are tied to RtpSenders, it's
+  // no longer relevant.
   virtual const AudioTrackInterface* track() const = 0;
 
   // Returns the tones remaining to be played out.
diff --git a/webrtc/api/jsep.h b/webrtc/api/jsep.h
index 37aed46..d19ae3c 100644
--- a/webrtc/api/jsep.h
+++ b/webrtc/api/jsep.h
@@ -8,7 +8,14 @@
  *  be found in the AUTHORS file in the root of the source tree.
  */
 
-// Interfaces matching the draft-ietf-rtcweb-jsep-01.
+// This file contains declarations of interfaces that wrap SDP-related
+// constructs; session descriptions and ICE candidates. The inner "cricket::"
+// objects shouldn't be accessed directly; the intention is that an application
+// using the PeerConnection API only creates these objects from strings, and
+// them passes them into the PeerConnection.
+//
+// Though in the future, we're planning to provide an SDP parsing API, with a
+// structure more friendly than cricket::SessionDescription.
 
 #ifndef WEBRTC_API_JSEP_H_
 #define WEBRTC_API_JSEP_H_
@@ -36,18 +43,21 @@
 };
 
 // Class representation of an ICE candidate.
+//
 // An instance of this interface is supposed to be owned by one class at
 // a time and is therefore not expected to be thread safe.
+//
+// An instance can be created by CreateIceCandidate.
 class IceCandidateInterface {
  public:
   virtual ~IceCandidateInterface() {}
-  /// If present, this contains the identierfier of the "media stream
-  // identification" as defined in [RFC 3388] for m-line this candidate is
-  // assocated with.
+  // If present, this is the value of the "a=mid" attribute of the candidate's
+  // m= section in SDP, which identifies the m= section.
   virtual std::string sdp_mid() const = 0;
-  // This indeicates the index (starting at zero) of m-line in the SDP this
-  // candidate is assocated with.
+  // This indicates the index (starting at zero) of m= section this candidate
+  // is assocated with. Needed when an endpoint doesn't support MIDs.
   virtual int sdp_mline_index() const = 0;
+  // Only for use internally.
   virtual const cricket::Candidate& candidate() const = 0;
   // Creates a SDP-ized form of this candidate.
   virtual bool ToString(std::string* out) const = 0;
@@ -55,15 +65,14 @@
 
 // Creates a IceCandidateInterface based on SDP string.
 // Returns NULL if the sdp string can't be parsed.
-// |error| can be NULL if doesn't care about the failure reason.
+// |error| may be NULL.
 IceCandidateInterface* CreateIceCandidate(const std::string& sdp_mid,
                                           int sdp_mline_index,
                                           const std::string& sdp,
                                           SdpParseError* error);
 
-// This class represents a collection of candidates for a specific m-line.
-// This class is used in SessionDescriptionInterface to represent all known
-// candidates for a certain m-line.
+// This class represents a collection of candidates for a specific m= section.
+// Used in SessionDescriptionInterface.
 class IceCandidateCollection {
  public:
   virtual ~IceCandidateCollection() {}
@@ -73,9 +82,12 @@
   virtual const IceCandidateInterface* at(size_t index) const = 0;
 };
 
-// Class representation of a Session description.
-// An instance of this interface is supposed to be owned by one class at
-// a time and is therefore not expected to be thread safe.
+// Class representation of an SDP session description.
+//
+// An instance of this interface is supposed to be owned by one class at a time
+// and is therefore not expected to be thread safe.
+//
+// An instance can be created by CreateSessionDescription.
 class SessionDescriptionInterface {
  public:
   // Supported types:
@@ -84,44 +96,59 @@
   static const char kAnswer[];
 
   virtual ~SessionDescriptionInterface() {}
+
+  // Only for use internally.
   virtual cricket::SessionDescription* description() = 0;
   virtual const cricket::SessionDescription* description() const = 0;
+
   // Get the session id and session version, which are defined based on
   // RFC 4566 for the SDP o= line.
   virtual std::string session_id() const = 0;
   virtual std::string session_version() const = 0;
+
+  // kOffer/kPrAnswer/kAnswer
   virtual std::string type() const = 0;
+
   // Adds the specified candidate to the description.
+  //
   // Ownership is not transferred.
-  // Returns false if the session description does not have a media section that
-  // corresponds to the |candidate| label.
+  //
+  // Returns false if the session description does not have a media section
+  // that corresponds to |candidate.sdp_mid()| or
+  // |candidate.sdp_mline_index()|.
   virtual bool AddCandidate(const IceCandidateInterface* candidate) = 0;
-  // Removes the candidates from the description.
+
+  // Removes the candidates from the description, if found.
+  //
   // Returns the number of candidates removed.
   virtual size_t RemoveCandidates(
       const std::vector<cricket::Candidate>& candidates) { return 0; }
 
-  // Returns the number of m- lines in the session description.
+  // Returns the number of m= sections in the session description.
   virtual size_t number_of_mediasections() const = 0;
-  // Returns a collection of all candidates that belong to a certain m-line
+
+  // Returns a collection of all candidates that belong to a certain m=
+  // section.
   virtual const IceCandidateCollection* candidates(
       size_t mediasection_index) const = 0;
+
   // Serializes the description to SDP.
   virtual bool ToString(std::string* out) const = 0;
 };
 
-// Creates a SessionDescriptionInterface based on SDP string and the type.
+// Creates a SessionDescriptionInterface based on the SDP string and the type.
 // Returns NULL if the sdp string can't be parsed or the type is unsupported.
-// |error| can be NULL if doesn't care about the failure reason.
+// |error| may be NULL.
 SessionDescriptionInterface* CreateSessionDescription(const std::string& type,
                                                       const std::string& sdp,
                                                       SdpParseError* error);
 
-// Jsep CreateOffer and CreateAnswer callback interface.
+// CreateOffer and CreateAnswer callback interface.
 class CreateSessionDescriptionObserver : public rtc::RefCountInterface {
  public:
-  // The implementation of the CreateSessionDescriptionObserver takes
-  // the ownership of the |desc|.
+  // This callback transfers the ownership of the |desc|.
+  // TODO(deadbeef): Make this take an std::unique_ptr<> to avoid confusion
+  // around ownership.
   virtual void OnSuccess(SessionDescriptionInterface* desc) = 0;
   virtual void OnFailure(const std::string& error) = 0;
 
@@ -129,7 +156,7 @@
   ~CreateSessionDescriptionObserver() {}
 };
 
-// Jsep SetLocalDescription and SetRemoteDescription callback interface.
+// SetLocalDescription and SetRemoteDescription callback interface.
 class SetSessionDescriptionObserver : public rtc::RefCountInterface {
  public:
   virtual void OnSuccess() = 0;
diff --git a/webrtc/api/jsepicecandidate.h b/webrtc/api/jsepicecandidate.h
index af06431..f068637 100644
--- a/webrtc/api/jsepicecandidate.h
+++ b/webrtc/api/jsepicecandidate.h
@@ -8,7 +8,8 @@
  *  be found in the AUTHORS file in the root of the source tree.
  */
 
-// Implements the IceCandidateInterface.
+// TODO(deadbeef): Move this out of api/; it's an implementation detail and
+// shouldn't be used externally.
 
 #ifndef WEBRTC_API_JSEPICECANDIDATE_H_
 #define WEBRTC_API_JSEPICECANDIDATE_H_
@@ -23,13 +24,14 @@
 
 namespace webrtc {
 
+// Implementation of IceCandidateInterface.
 class JsepIceCandidate : public IceCandidateInterface {
  public:
   JsepIceCandidate(const std::string& sdp_mid, int sdp_mline_index);
   JsepIceCandidate(const std::string& sdp_mid, int sdp_mline_index,
                    const cricket::Candidate& candidate);
   ~JsepIceCandidate();
-  // |error| can be NULL if don't care about the failure reason.
+  // |err| may be NULL.
   bool Initialize(const std::string& sdp, SdpParseError* err);
   void SetCandidate(const cricket::Candidate& candidate) {
     candidate_ = candidate;
@@ -51,8 +53,7 @@
   RTC_DISALLOW_COPY_AND_ASSIGN(JsepIceCandidate);
 };
 
-// Implementation of IceCandidateCollection.
-// This implementation stores JsepIceCandidates.
+// Implementation of IceCandidateCollection which stores JsepIceCandidates.
 class JsepCandidateCollection : public IceCandidateCollection {
  public:
   JsepCandidateCollection() {}
@@ -66,6 +67,8 @@
   }
   virtual bool HasCandidate(const IceCandidateInterface* candidate) const;
   // Adds and takes ownership of the JsepIceCandidate.
+  // TODO(deadbeef): Make this use an std::unique_ptr<>, so ownership logic is
+  // more clear.
   virtual void add(JsepIceCandidate* candidate) {
     candidates_.push_back(candidate);
   }
@@ -73,6 +76,7 @@
     return candidates_[index];
   }
   // Removes the candidate that has a matching address and protocol.
+  //
   // Returns the number of candidates that were removed.
   size_t remove(const cricket::Candidate& candidate);
 
diff --git a/webrtc/api/jsepsessiondescription.h b/webrtc/api/jsepsessiondescription.h
index 8f2ab5f..b5e1b4f 100644
--- a/webrtc/api/jsepsessiondescription.h
+++ b/webrtc/api/jsepsessiondescription.h
@@ -8,7 +8,8 @@
  *  be found in the AUTHORS file in the root of the source tree.
  */
 
-// Implements the SessionDescriptionInterface.
+// TODO(deadbeef): Move this out of api/; it's an implementation detail and
+// shouldn't be used externally.
 
 #ifndef WEBRTC_API_JSEPSESSIONDESCRIPTION_H_
 #define WEBRTC_API_JSEPSESSIONDESCRIPTION_H_
@@ -28,15 +29,18 @@
 
 namespace webrtc {
 
+// Implementation of SessionDescriptionInterface.
 class JsepSessionDescription : public SessionDescriptionInterface {
  public:
   explicit JsepSessionDescription(const std::string& type);
   virtual ~JsepSessionDescription();
 
-  // |error| can be NULL if don't care about the failure reason.
+  // |error| may be NULL.
   bool Initialize(const std::string& sdp, SdpParseError* error);
 
   // Takes ownership of |description|.
+  // TODO(deadbeef): Make this use an std::unique_ptr<>, so ownership logic is
+  // more clear.
   bool Initialize(cricket::SessionDescription* description,
       const std::string& session_id,
       const std::string& session_version);
@@ -56,7 +60,7 @@
   virtual std::string type() const {
     return type_;
   }
-  // Allow changing the type. Used for testing.
+  // Allows changing the type. Used for testing.
   void set_type(const std::string& type) { type_ = type; }
   virtual bool AddCandidate(const IceCandidateInterface* candidate);
   virtual size_t RemoveCandidates(
diff --git a/webrtc/api/mediaconstraintsinterface.h b/webrtc/api/mediaconstraintsinterface.h
index 2017890..8dafea4 100644
--- a/webrtc/api/mediaconstraintsinterface.h
+++ b/webrtc/api/mediaconstraintsinterface.h
@@ -28,9 +28,12 @@
 
 namespace webrtc {
 
-// MediaConstraintsInterface
 // Interface used for passing arguments about media constraints
 // to the MediaStream and PeerConnection implementation.
+//
+// Constraints may be either "mandatory", which means that unless satisfied,
+// the method taking the constraints should fail, or "optional", which means
+// they may not be satisfied..
 class MediaConstraintsInterface {
  public:
   struct Constraint {
diff --git a/webrtc/api/mediastreaminterface.h b/webrtc/api/mediastreaminterface.h
index a52f0c7..59ca66c 100644
--- a/webrtc/api/mediastreaminterface.h
+++ b/webrtc/api/mediastreaminterface.h
@@ -53,8 +53,8 @@
   virtual ~NotifierInterface() {}
 };
 
-// Base class for sources. A MediaStreamTrack have an underlying source that
-// provide media. A source can be shared with multiple tracks.
+// Base class for sources. A MediaStreamTrack has an underlying source that
+// provides media. A source can be shared by multiple tracks.
 class MediaSourceInterface : public rtc::RefCountInterface,
                              public NotifierInterface {
  public:
@@ -73,7 +73,8 @@
   virtual ~MediaSourceInterface() {}
 };
 
-// Information about a track.
+// C++ version of MediaStreamTrack.
+// See: https://www.w3.org/TR/mediacapture-streams/#mediastreamtrack
 class MediaStreamTrackInterface : public rtc::RefCountInterface,
                                   public NotifierInterface {
  public:
@@ -90,17 +91,24 @@
   // object is a subclass of VideoTrackInterface. It is typically used
   // to protect a static_cast<> to the corresponding subclass.
   virtual std::string kind() const = 0;
+
+  // Track identifier.
   virtual std::string id() const = 0;
+
+  // A disabled track will produce silence (if audio) or black frames (if
+  // video). Can be disabled and re-enabled.
   virtual bool enabled() const = 0;
-  virtual TrackState state() const = 0;
   virtual bool set_enabled(bool enable) = 0;
 
+  // Live or ended. A track will never be live again after becoming ended.
+  virtual TrackState state() const = 0;
+
  protected:
   virtual ~MediaStreamTrackInterface() {}
 };
 
-// VideoTrackSourceInterface is a reference counted source used for VideoTracks.
-// The same source can be used in multiple VideoTracks.
+// VideoTrackSourceInterface is a reference counted source used for
+// VideoTracks. The same source can be used by multiple VideoTracks.
 class VideoTrackSourceInterface
     : public MediaSourceInterface,
       public rtc::VideoSourceInterface<VideoFrame> {
@@ -114,7 +122,7 @@
   // Indicates that parameters suitable for screencasts should be automatically
   // applied to RtpSenders.
   // TODO(perkj): Remove these once all known applications have moved to
-  // explicitly setting suitable parameters for screencasts and dont' need this
+  // explicitly setting suitable parameters for screencasts and don't need this
   // implicit behavior.
   virtual bool is_screencast() const = 0;
 
@@ -125,9 +133,10 @@
   // the encoder.
   virtual rtc::Optional<bool> needs_denoising() const = 0;
 
-  // Returns false if no stats are available, e.g, for a remote
-  // source, or a source which has not seen its first frame yet.
-  // Should avoid blocking.
+  // Returns false if no stats are available, e.g, for a remote source, or a
+  // source which has not seen its first frame yet.
+  //
+  // Implementation should avoid blocking.
   virtual bool GetStats(Stats* stats) = 0;
 
  protected:
@@ -143,7 +152,8 @@
   // See https://crbug.com/653531 and https://github.com/WICG/mst-content-hint.
   enum class ContentHint { kNone, kFluid, kDetailed };
 
-  // Register a video sink for this track.
+  // Register a video sink for this track. Used to connect the track to the
+  // underlying video engine.
   void AddOrUpdateSink(rtc::VideoSinkInterface<VideoFrame>* sink,
                        const rtc::VideoSinkWants& wants) override {}
   void RemoveSink(rtc::VideoSinkInterface<VideoFrame>* sink) override {}
@@ -171,7 +181,7 @@
 };
 
 // AudioSourceInterface is a reference counted source used for AudioTracks.
-// The same source can be used in multiple AudioTracks.
+// The same source can be used by multiple AudioTracks.
 class AudioSourceInterface : public MediaSourceInterface {
  public:
   class AudioObserver {
@@ -182,14 +192,15 @@
     virtual ~AudioObserver() {}
   };
 
-  // TODO(xians): Makes all the interface pure virtual after Chrome has their
-  // implementations.
-  // Sets the volume to the source. |volume| is in  the range of [0, 10].
+  // TODO(deadbeef): Makes all the interfaces pure virtual after they're
+  // implemented in chromium.
+
+  // Sets the volume of the source. |volume| is in  the range of [0, 10].
   // TODO(tommi): This method should be on the track and ideally volume should
   // be applied in the track in a way that does not affect clones of the track.
   virtual void SetVolume(double volume) {}
 
-  // Registers/unregisters observer to the audio source.
+  // Registers/unregisters observers to the audio source.
   virtual void RegisterAudioObserver(AudioObserver* observer) {}
   virtual void UnregisterAudioObserver(AudioObserver* observer) {}
 
@@ -235,7 +246,8 @@
 
 class AudioTrackInterface : public MediaStreamTrackInterface {
  public:
-  // TODO(xians): Figure out if the following interface should be const or not.
+  // TODO(deadbeef): Figure out if the following interface should be const or
+  // not.
   virtual AudioSourceInterface* GetSource() const =  0;
 
   // Add/Remove a sink that will receive the audio data from the track.
@@ -244,15 +256,16 @@
 
   // Get the signal level from the audio track.
   // Return true on success, otherwise false.
-  // TODO(xians): Change the interface to int GetSignalLevel() and pure virtual
-  // after Chrome has the correct implementation of the interface.
+  // TODO(deadbeef): Change the interface to int GetSignalLevel() and pure
+  // virtual after it's implemented in chromium.
   virtual bool GetSignalLevel(int* level) { return false; }
 
   // Get the audio processor used by the audio track. Return NULL if the track
   // does not have any processor.
-  // TODO(xians): Make the interface pure virtual.
-  virtual rtc::scoped_refptr<AudioProcessorInterface>
-      GetAudioProcessor() { return NULL; }
+  // TODO(deadbeef): Make the interface pure virtual.
+  virtual rtc::scoped_refptr<AudioProcessorInterface> GetAudioProcessor() {
+    return nullptr;
+  }
 
  protected:
   virtual ~AudioTrackInterface() {}
@@ -263,6 +276,14 @@
 typedef std::vector<rtc::scoped_refptr<VideoTrackInterface> >
     VideoTrackVector;
 
+// C++ version of https://www.w3.org/TR/mediacapture-streams/#mediastream.
+//
+// A major difference is that remote audio/video tracks (received by a
+// PeerConnection/RtpReceiver) are not synchronized simply by adding them to
+// the same stream; a session description with the correct "a=msid" attributes
+// must be pushed down.
+//
+// Thus, this interface acts as simply a container for tracks.
 class MediaStreamInterface : public rtc::RefCountInterface,
                              public NotifierInterface {
  public:
diff --git a/webrtc/api/mediastreamproxy.h b/webrtc/api/mediastreamproxy.h
index fe11300..15b40ed 100644
--- a/webrtc/api/mediastreamproxy.h
+++ b/webrtc/api/mediastreamproxy.h
@@ -18,6 +18,8 @@
 
 namespace webrtc {
 
+// TODO(deadbeef): Move this to .cc file and out of api/. What threads methods
+// are called on is an implementation detail.
 BEGIN_SIGNALING_PROXY_MAP(MediaStream)
   PROXY_SIGNALING_THREAD_DESTRUCTOR()
   PROXY_CONSTMETHOD0(std::string, label)
diff --git a/webrtc/api/mediastreamtrackproxy.h b/webrtc/api/mediastreamtrackproxy.h
index 9a3cb42..605f3f2 100644
--- a/webrtc/api/mediastreamtrackproxy.h
+++ b/webrtc/api/mediastreamtrackproxy.h
@@ -21,6 +21,9 @@
 
 namespace webrtc {
 
+// TODO(deadbeef): Move this to .cc file and out of api/. What threads methods
+// are called on is an implementation detail.
+
 BEGIN_SIGNALING_PROXY_MAP(AudioTrack)
   PROXY_SIGNALING_THREAD_DESTRUCTOR()
   PROXY_CONSTMETHOD0(std::string, kind)
diff --git a/webrtc/api/notifier.h b/webrtc/api/notifier.h
index eabaa3c..878d01c 100644
--- a/webrtc/api/notifier.h
+++ b/webrtc/api/notifier.h
@@ -18,7 +18,8 @@
 
 namespace webrtc {
 
-// Implement a template version of a notifier.
+// Implements a template version of a notifier.
+// TODO(deadbeef): This is an implementation detail; move out of api/.
 template <class T>
 class Notifier : public T {
  public:
diff --git a/webrtc/api/peerconnectionfactoryproxy.h b/webrtc/api/peerconnectionfactoryproxy.h
index d41aad2..e829cca 100644
--- a/webrtc/api/peerconnectionfactoryproxy.h
+++ b/webrtc/api/peerconnectionfactoryproxy.h
@@ -21,6 +21,8 @@
 
 namespace webrtc {
 
+// TODO(deadbeef): Move this to .cc file and out of api/. What threads methods
+// are called on is an implementation detail.
 BEGIN_SIGNALING_PROXY_MAP(PeerConnectionFactory)
   PROXY_SIGNALING_THREAD_DESTRUCTOR()
   PROXY_METHOD1(void, SetOptions, const Options&)
diff --git a/webrtc/api/peerconnectioninterface.h b/webrtc/api/peerconnectioninterface.h
index 6cc8be7..ea94f50 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 @@
     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 @@
     // 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 @@
   // 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 @@
     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 @@
     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 @@
   // 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 @@
       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 @@
   // 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 @@
       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 @@
   // 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 @@
   ~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 @@
   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 @@
   ~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 @@
 
   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 @@
       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 @@
   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 @@
 // |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,
diff --git a/webrtc/api/peerconnectionproxy.h b/webrtc/api/peerconnectionproxy.h
index 76b45d6..2375dd4 100644
--- a/webrtc/api/peerconnectionproxy.h
+++ b/webrtc/api/peerconnectionproxy.h
@@ -19,7 +19,8 @@
 
 namespace webrtc {
 
-// Define proxy for PeerConnectionInterface.
+// TODO(deadbeef): Move this to .cc file and out of api/. What threads methods
+// are called on is an implementation detail.
 BEGIN_SIGNALING_PROXY_MAP(PeerConnection)
   PROXY_SIGNALING_THREAD_DESTRUCTOR()
   PROXY_METHOD0(rtc::scoped_refptr<StreamCollectionInterface>, local_streams)
diff --git a/webrtc/api/proxy.h b/webrtc/api/proxy.h
index f834790..5634cfe 100644
--- a/webrtc/api/proxy.h
+++ b/webrtc/api/proxy.h
@@ -10,6 +10,7 @@
 
 // This file contains Macros for creating proxies for webrtc MediaStream and
 // PeerConnection classes.
+// TODO(deadbeef): Move this to pc/; this is part of the implementation.
 
 //
 // Example usage:
diff --git a/webrtc/api/rtpreceiverinterface.h b/webrtc/api/rtpreceiverinterface.h
index 4e47c9a..8607d93 100644
--- a/webrtc/api/rtpreceiverinterface.h
+++ b/webrtc/api/rtpreceiverinterface.h
@@ -54,6 +54,7 @@
   // but this API also applies them to receivers, similar to ORTC:
   // http://ortc.org/wp-content/uploads/2016/03/ortc.html#rtcrtpparameters*.
   virtual RtpParameters GetParameters() const = 0;
+  // Currently, doesn't support changing any parameters, but may in the future.
   virtual bool SetParameters(const RtpParameters& parameters) = 0;
 
   // Does not take ownership of observer.
@@ -65,6 +66,8 @@
 };
 
 // Define proxy for RtpReceiverInterface.
+// TODO(deadbeef): Move this to .cc file and out of api/. What threads methods
+// are called on is an implementation detail.
 BEGIN_SIGNALING_PROXY_MAP(RtpReceiver)
   PROXY_SIGNALING_THREAD_DESTRUCTOR()
   PROXY_CONSTMETHOD0(rtc::scoped_refptr<MediaStreamTrackInterface>, track)
diff --git a/webrtc/api/rtpsenderinterface.h b/webrtc/api/rtpsenderinterface.h
index 68547b0..f2b6766 100644
--- a/webrtc/api/rtpsenderinterface.h
+++ b/webrtc/api/rtpsenderinterface.h
@@ -47,9 +47,13 @@
   // to uniquely identify a receiver until we implement Unified Plan SDP.
   virtual std::string id() const = 0;
 
+  // Returns a list of streams associated with this sender's track. Although we
+  // only support one track per stream, in theory the API allows for multiple.
   virtual std::vector<std::string> stream_ids() const = 0;
 
   virtual RtpParameters GetParameters() const = 0;
+  // Note that only a subset of the parameters can currently be changed. See
+  // rtpparameters.h
   virtual bool SetParameters(const RtpParameters& parameters) = 0;
 
   // Returns null for a video sender.
@@ -60,6 +64,8 @@
 };
 
 // Define proxy for RtpSenderInterface.
+// TODO(deadbeef): Move this to .cc file and out of api/. What threads methods
+// are called on is an implementation detail.
 BEGIN_SIGNALING_PROXY_MAP(RtpSender)
   PROXY_SIGNALING_THREAD_DESTRUCTOR()
   PROXY_METHOD1(bool, SetTrack, MediaStreamTrackInterface*)
diff --git a/webrtc/api/udptransportinterface.h b/webrtc/api/udptransportinterface.h
index 1a28531..30858e6 100644
--- a/webrtc/api/udptransportinterface.h
+++ b/webrtc/api/udptransportinterface.h
@@ -45,6 +45,8 @@
   virtual rtc::SocketAddress GetRemoteAddress() const = 0;
 };
 
+// TODO(deadbeef): Move this to .cc file and out of api/. What threads methods
+// are called on is an implementation detail.
 BEGIN_OWNED_PROXY_MAP(UdpTransport)
   PROXY_WORKER_THREAD_DESTRUCTOR()
   PROXY_WORKER_CONSTMETHOD0(rtc::SocketAddress, GetLocalAddress)
diff --git a/webrtc/api/videosourceproxy.h b/webrtc/api/videosourceproxy.h
index b678acb..a00a21d 100644
--- a/webrtc/api/videosourceproxy.h
+++ b/webrtc/api/videosourceproxy.h
@@ -16,10 +16,10 @@
 
 namespace webrtc {
 
-// VideoTrackSourceInterface makes sure the real VideoTrackSourceInterface
-// implementation is
-// destroyed on the signaling thread and marshals all method calls to the
-// signaling thread.
+// Makes sure the real VideoTrackSourceInterface implementation is destroyed on
+// the signaling thread and marshals all method calls to the signaling thread.
+// TODO(deadbeef): Move this to .cc file and out of api/. What threads methods
+// are called on is an implementation detail.
 BEGIN_PROXY_MAP(VideoTrackSource)
   PROXY_SIGNALING_THREAD_DESTRUCTOR()
   PROXY_CONSTMETHOD0(SourceState, state)