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

webrtc/api/jsep.h

Index: webrtc/api/jsep.h
diff --git a/webrtc/api/jsep.h b/webrtc/api/jsep.h
index 37aed46b5b61257567db671afab95203583b6a8a..d19ae3c7d0a5d9c3db1872de5be403a7ff6b7bed 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 @@ struct SdpParseError {
 };
 
 // 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 @@ class IceCandidateInterface {
 
 // 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 @@ class IceCandidateCollection {
   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 @@ class SessionDescriptionInterface {
   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 @@ class CreateSessionDescriptionObserver : public rtc::RefCountInterface {
   ~CreateSessionDescriptionObserver() {}
 };
 
-// Jsep SetLocalDescription and SetRemoteDescription callback interface.
+// SetLocalDescription and SetRemoteDescription callback interface.
 class SetSessionDescriptionObserver : public rtc::RefCountInterface {
  public:
   virtual void OnSuccess() = 0;