Update API for Objective-C RTCPeerConnection.

webrtc/api/objc/RTCPeerConnection.h

+/*
+ *  Copyright 2015 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.
+ */
+
+#import <Foundation/Foundation.h>
+
+@class RTCConfiguration;
+@class RTCDataChannel;
+@class RTCDataChannelConfiguration;
+@class RTCIceCandidate;
+@class RTCMediaConstraints;
+@class RTCMediaStream;
+@class RTCMediaStreamTrack;
+@class RTCPeerConnectionFactory;
+@class RTCSessionDescription;
+@class RTCStatsReport;
+
+extern NSString * _Nonnull const kRTCPeerConnectionErrorDomain;
+extern int const kRTCSessionDescriptionErrorCode;
+
+/** Represents the signaling state of the peer connection. */
+typedef NS_ENUM(NSInteger, RTCSignalingState) {
+  RTCSignalingStateStable,
+  RTCSignalingStateHaveLocalOffer,
+  RTCSignalingStateHaveLocalPrAnswer,
+  RTCSignalingStateHaveRemoteOffer,
+  RTCSignalingStateHaveRemotePrAnswer,
+  RTCSignalingStateClosed,
+};
+
+/** Represents the ice connection state of the peer connection. */
+typedef NS_ENUM(NSInteger, RTCIceConnectionState) {
+  RTCIceConnectionStateNew,
+  RTCIceConnectionStateChecking,
+  RTCIceConnectionStateConnected,
+  RTCIceConnectionStateCompleted,
+  RTCIceConnectionStateFailed,
+  RTCIceConnectionStateDisconnected,
+  RTCIceConnectionStateClosed,
+  RTCIceConnectionStateMax,
+};
+
+/** Represents the ice gathering state of the peer connection. */
+typedef NS_ENUM(NSInteger, RTCIceGatheringState) {
+  RTCIceGatheringStateNew,
+  RTCIceGatheringStateGathering,
+  RTCIceGatheringStateComplete,
+};
+
+/** Represents the stats output level. */
+typedef NS_ENUM(NSInteger, RTCStatsOutputLevel) {
+  RTCStatsOutputLevelStandard,
+  RTCStatsOutputLevelDebug,
+};
+
+NS_ASSUME_NONNULL_BEGIN
+
+@class RTCPeerConnection;
+
+@protocol RTCPeerConnectionDelegate <NSObject>
+
+/** Called when the SignalingState changed. */
+- (void)peerConnection:(RTCPeerConnection *)peerConnection
+    didChangeSignalingState:(RTCSignalingState)stateChanged;
+
+/** Called when media is received on a new stream from remote peer. */
+- (void)peerConnection:(RTCPeerConnection *)peerConnection
+           addedStream:(RTCMediaStream *)stream;

[tkchin_webrtc, 2016/02/10 18:54:40]

didAddStream

[hjon_webrtc, 2016/02/11 00:25:08]

Done.

+
+/** Called when a remote peer closes a stream. */
+- (void)peerConnection:(RTCPeerConnection *)peerConnection
+         removedStream:(RTCMediaStream *)stream;

[tkchin_webrtc, 2016/02/10 18:54:40]

didRemoveStream

[hjon_webrtc, 2016/02/11 00:25:08]

Done.

+
+/** Called when negotiation is needed, for example ICE has restarted. */
+- (void)peerConnectionNeedsNegotiation:(RTCPeerConnection *)peerConnection;

[tkchin_webrtc, 2016/02/10 18:54:40]

peerConnectionShouldNegotiate

[hjon_webrtc, 2016/02/11 00:25:08]

Done.

+
+/** Called any time the IceConnectionState changes. */
+- (void)peerConnection:(RTCPeerConnection *)peerConnection
+    didChangeIceConnectionState:(RTCIceConnectionState)newState;
+
+/** Called any time the IceGatheringState changes. */
+- (void)peerConnection:(RTCPeerConnection *)peerConnection
+    didChangeIceGatheringState:(RTCIceGatheringState)newState;
+
+/** New ice candidate has been found. */
+- (void)peerConnection:(RTCPeerConnection *)peerConnection
+    didGenerateIceCandidate:(RTCIceCandidate *)candidate;
+
+/** New data channel has been opened. */
+- (void)peerConnection:(RTCPeerConnection *)peerConnection
+    didOpenDataChannel:(RTCDataChannel *)dataChannel;
+
+@end
+
+
+@interface RTCPeerConnection : NSObject
+
+/**
+ * The object that will be notifed about events such as state changes and
+ * streams being added or removed.
+ */
+@property(nonatomic, weak) id<RTCPeerConnectionDelegate> delegate;
+
+/** The current remote description. */

[tkchin_webrtc, 2016/02/10 18:54:40]

? Comment does not match

[hjon_webrtc, 2016/02/11 00:25:08]

Done.

+@property(nonatomic, readonly) NSArray *localStreams;
+
+/** The current local description. */
+@property(nonatomic, readonly, nullable)
+    RTCSessionDescription *localDescription;
+
+/** The pending or current remote description. */

[tkchin_webrtc, 2016/02/10 18:54:40]

What does it mean to be a pending description? 
I think it is okay to remove comments for things that are self-documenting.
e.g. signalingState -> pretty clear what that is

[hjon_webrtc, 2016/02/11 00:25:08]

I removed most of the comments in this section, as I don't feel they provide any
useful information beyond the property name. Let me know if you think any need
to be added back.

+@property(nonatomic, readonly, nullable)
+    RTCSessionDescription *remoteDescription;
+
+/** The signaling state of this RTCPeerConnection instance. */
+@property(nonatomic, readonly) RTCSignalingState signalingState;
+
+/** The ICE connection state of this RTCPeerConnection instance. */
+@property(nonatomic, readonly) RTCIceConnectionState iceConnectionState;
+
+/** The ICE gathering state of this RTCPeerConnection instance. */
+@property(nonatomic, readonly) RTCIceGatheringState iceGatheringState;
+
+- (instancetype)init NS_UNAVAILABLE;
+
+/**
+ * Initialize an RTCPeerConnection with a configuration, constraints, and
+ * delegate.
+ */
+- (instancetype)initWithFactory:(RTCPeerConnectionFactory *)factory
+                  configuration:(RTCConfiguration *)configuration
+                    constraints:(RTCMediaConstraints *)constraints
+                       delegate:(id<RTCPeerConnectionDelegate>)delegate
+    NS_DESIGNATED_INITIALIZER;
+
+/** Terminate all media and close the transport. */
+- (void)close;
+
+/** Provide a remote candidate to the ICE Agent. */
+- (void)addIceCandidate:(RTCIceCandidate *)candidate;
+
+/** Add a new media stream to be sent on this peer connection. */
+- (void)addStream:(RTCMediaStream *)stream;
+
+/** Remove the given media stream from this peer connection. */
+- (void)removeStream:(RTCMediaStream *)stream;
+
+/** Generate an SDP offer. */
+- (void)offerForConstraints:(RTCMediaConstraints *)constraints
+          completionHandler:(void (^)

[tkchin_webrtc, 2016/02/10 18:54:40]

formatting
(void (^)(RTCSessionDescription *,
          NSError, *))completionHandler

[hjon_webrtc, 2016/02/11 00:25:08]

Done.

+  (RTCSessionDescription *sessionDescription, NSError *error))completionHandler;
+
+/** Generate an SDP answer. */
+- (void)answerForConstraints:(RTCMediaConstraints *)constraints
+           completionHandler:(void (^)
+  (RTCSessionDescription *sessionDescription, NSError *error))completionHandler;

[tkchin_webrtc, 2016/02/10 18:54:40]

ditto

[hjon_webrtc, 2016/02/11 00:25:08]

Done.

+
+/** Apply the supplied RTCSessionDescription as the local description. */
+- (void)setLocalDescription:(RTCSessionDescription *)sdp
+          completionHandler:(void (^)(NSError *error))completionHandler;
+
+/** Apply the supplied RTCSessionDescription as the remote description. */
+- (void)setRemoteDescription:(RTCSessionDescription *)sdp
+           completionHandler:(void (^)(NSError *error))completionHandler;
+
+@end
+
+@interface RTCPeerConnection (DataChannel)
+
+/** Create a new data channel with the given label and configuration. */
+- (RTCDataChannel *)dataChannelWithLabel:(NSString *)label

[tkchin_webrtc, 2016/02/10 18:54:40]

nit: dataChannelForLabel:configuration:

[hjon_webrtc, 2016/02/11 00:25:08]

Done.

+    configuration:(RTCDataChannelConfiguration *)configuration;
+
+@end
+
+@interface RTCPeerConnection (Stats)
+
+/**
+ * Gather stats for the given RTCMediaStreamTrack. If |mediaStreamTrack| is nil
+ * statistics are gathered for all tracks.
+ */
+- (void)statsForMediaStreamTrack:

[tkchin_webrtc, 2016/02/10 18:54:40]

nit: unless this is explicitly in the spec,
statsForTrack:outputLevel:completionHandler seems more concise

[hjon_webrtc, 2016/02/11 00:25:08]

Done.

+    (nullable RTCMediaStreamTrack *)mediaStreamTrack
+                statsOutputLevel:(RTCStatsOutputLevel)statsOutputLevel
+               completionHandler:
+    (void (^)(NSArray<RTCStatsReport *> *stats))completionHandler;

[tkchin_webrtc, 2016/02/10 18:54:40]

no error?

[hjon_webrtc, 2016/02/11 00:25:08]

Feels a little surprising, but there's not an error in the spec nor in the C++. 

+
+@end
+
+NS_ASSUME_NONNULL_END