Draft: draft-ietf-rtcweb-jsep

Commentary: Updated a few sentences in Section 1 regarding XMPP and SIP libraries and the API surface . Removed comments . issue 5 and issue 6 . 
 6 ) [ rfced ] Section 1.2 : We had trouble parsing this sentence . If the suggested text is not correct , please clarify " as well as creating ... " Original ( the previous sentence is included for context ): A second approach that was considered but not chosen was to decouple the management of the media control objects from session descriptions , instead offering APIs that would control each component directly . This was rejected based on the argument that requiring exposure of this level of complexity to the application programmer would not be beneficial ; it would result in an API where even a simple example would require a significant amount of code to orchestrate all the needed interactions , as well as creating a large API surface that needed to be agreed upon and documented . Suggested : This was rejected based on the argument that requiring exposure of this level of complexity to the application programmer would not be beneficial ; it would ( 1 ) result in an API where even a simple example would require a significant amount of code to orchestrate all the needed interactions and ( 2 ) create a large API surface that needed to be agreed upon and documented . 
 This mostly LGTM , but the final sentence reads a bit oddly now - perhaps
Paragraph (version A):
One way to make life easier for the application is to provide a
JavaScript library that hides this complexity from the developer;
said library would implement a given signaling protocol along with
its state machine and serialization code, presenting a higher-level
call-oriented interface to the application developer.  For example,
libraries exist to adapt the JSEP API into an API suitable for a SIP
interface or an Extensible Messaging and Presence Protocol (XMPP)
interface RFC6120.  Thus, JSEP provides greater control for the
experienced developer without forcing any additional complexity on
the novice developer.
Paragraph (version B):
One way to make life easier for the application is to provide a
JavaScript library that hides this complexity from the developer;
said library would implement a given signaling protocol along with
its state machine and serialization code, presenting a higher-level
call-oriented interface to the application developer.  For example,
libraries exist to provide implementations of the SIP RFC3261 and
Extensible Messaging and Presence Protocol (XMPP) RFC6120 signaling
protocols atop the JSEP API.  Thus, JSEP provides greater control for
the experienced developer without forcing any additional complexity
on the novice developer.
Paragraph (version A):
A second approach that was considered but not chosen was to decouple
the management of the media control objects from session
descriptions, instead offering APIs that would control each component
directly.  This was rejected based on the argument that requiring
exposure of this level of complexity to the application programmer
would not be beneficial; it would result in an API where even a
simple example would require a significant amount of code to
orchestrate all the needed interactions, as well as creating a large
API surface that needed to be agreed upon and documented.  In
addition, these API points could be called in any order, resulting in
a more complex set of interactions with the media subsystem than the
JSEP approach, which specifies how session descriptions are to be
evaluated and applied.
Paragraph (version B):
A second approach that was considered but not chosen was to decouple
the management of the media control objects from session
descriptions, instead offering APIs that would control each component
directly.  This was rejected based on the argument that requiring
exposure of this level of complexity to the application programmer
would not be beneficial; it would (1) result in an API where even a
simple example would require a significant amount of code to
orchestrate all the needed interactions and (2) create a large API
surface that would need to be agreed upon and documented.  In
addition, these API points could be called in any order, resulting in
a more complex set of interactions with the media subsystem than the
JSEP approach, which specifies how session descriptions are to be
evaluated and applied.