jiebi/ids-paragraph-commentary-corpus huggingface dataset:
Draft: draft-ietf-taps-interface

Commentary: batch sending , as currently specified , means that you already have to have all messages ready in the application because you can declare a patch . That means you have to potentially " buffer " some message in the application . Would n't it may be better / easier to have a message property that indicates that a certain message should wait ( probably up until a maximum time ) for the next message and then buffer it in the transport instead ? 
 We can just clarify the text that the batch may be an arbitrarily long - running block of code , and not require knowing up front all of the data . 
 Could also allow begin batch / end batch . Explain use case around optimizing send performance .
Paragraph (version B):
The semantics for starting and ending a batch can be implementation-
specific, but need to allow multiple Send Actions to be enqueued.
Draft: draft-ietf-taps-interface

Commentary: Apple does this : it may be more convenient than what we currently have ( or do we have it unspecified ? My interpretation of our text would have been to use only one receive handler associated to the Connection ) . E.g. , if an application expects 3 different types of messages to be received in sequence , it can hand over three different receive handlers in Apple 's case , and that seems useful . Apple also has a " completion " handler per sent event , handed over as a parameter to " send " . Is this necessary ? Who needs 3 different " Sent " handlers for 3 different messages - should n't the " sent " handler rather be a singular per - Connection thing ? 
 I think this gets into an implementation - specific area . If the language has an easy way to provide a unique completion / closure for a given invocation of Receive ( ) , then I think it is preferable to do this to having a single function . If anything , it may be nice to make a not for Received ( ) and  ( ) that they should , if supported by the language , provide this kind of linking between calls and events . 
 I agree , and I assign this to  since he offered ( in an email ) to write text . Thanks a lot !
Paragraph (version B):
The interface should allow the application to correlate which Send
Action resulted in a particular Send Event.  The manner in which this
correlation is indicated is implementation-specific.
Paragraph (version B):
The interface should allow the application to correlate which call to
Receive resulted in a particular Receive Event.  The manner in which
this correlation is indicated is implementation-specific.
Draft: draft-ietf-taps-interface

Commentary: Looks fine to me . I wonder if we want to add some text and given some implementation hints . Not sure if that is needed but it could be useful ... ? 
 Looks good . 
 In section 7.1 of API it says : messageData : = " hello".bytes ( ) Connection . Send(messageData ) For some languages that are dynamic typed ( i.e. python ) this limits the usability of the API as it adds an unnecessary extra step to each send . To me this seems like it should be an implementation detail and not specified in the API . 
 What are the options other than raw bytes ? 
 In python you could just pass any type that gets automatically converted inside the API . For example , in our implementation you could just pass a string or integer that gets converted to bytes inside the implementation before sending . Also , if there is a TLV framer , you could just pass a [ type , value ] tuple without having to go through the message context . 
 We generally consider this a case for framers . However , I think it 's reasonable to assume that any of the objects used in a TAPS implementation should provide some way for the app to get at the underlying bytes ( and therefore , at least implicitly , the length ) . I do n't read this text as prohibiting the use of some object that is able . 
 I agree that this is an implementation detail that 's irrelevant to the abstract API . Can we close this issue ? 
 Requiring the data be accessible as a byte array is overly restrictive . Can we just remove " Message data is transferred as an array of bytes , and the resulting object contains both the byte array and the length of the array . " and the call ?
Paragraph (version A):
The most basic form of sending on a connection involves enqueuing a
single Data block as a complete Message, with default Message
Properties.  Message data is transferred as an array of bytes, and
the resulting object contains both the byte array and the length of
the array.
Paragraph (version B):
The most basic form of sending on a connection involves enqueuing a
single Data block as a complete Message, with default Message
Properties.
Draft: draft-ietf-taps-interface

Commentary: Resolving Editorial NiTs in section 1 
 Section 1 : This section contains a RFC2119 keyword that precedes the definition ! We use the words /abstract programming interface/ and the acronym /API/ but never tie these together . NiTs : /provide applications a way to / provide a way for applications to/ /as it comes at the cost of reduced portability / because it can reduce the portability./ /How these abstract concepts / The way these abstract concepts/ /is largely dependent on / mostly depends on/ 
 A PR for this issue has already been merged . 
 Looks good to me , thanks for doing this !
Paragraph (version A):
This document specifies a modern abstract programming interface (API)
atop the high-level architecture for transport services defined in I-
D.ietf-taps-arch.  It supports the asynchronous, atomic transmission
of messages over transport protocols and network paths dynamically
selected at runtime.  It is intended to replace the traditional BSD
sockets API as the common interface to the transport layer, in
environments where endpoints select from multiple interfaces and
potential transport protocols.
Paragraph (version B):
This document specifies a modern abstract application programming
interface (API) atop the high-level architecture for transport
services defined in I-D.ietf-taps-arch.  It supports the
asynchronous, atomic transmission of messages over transport
protocols and network paths dynamically selected at runtime.  It is
intended to replace the traditional BSD sockets API as the common
interface to the transport layer, in environments where endpoints
select from multiple interfaces and potential transport protocols.
Draft: draft-ietf-taps-interface

Commentary: Fixing three oddities in the abstract , issue 
 Odd English : /where endpoints have multiple interfaces and potential transport protocols to select from / where endpoints could select from multiple interfaces and potential transport protocols./ We use the words /abstract programming interface/ and the acronym /API/ but never tie these two together . I am not huge fan of : /lowest common denominator interface/ ... as an engineer , this sounds like a good thing , although /lowest/ is n't that clear , so I wonder if we can find a better term ? 
 Resolved in PR 
 LGTM modulo one nit
Paragraph (version A):
This document describes an abstract programming interface, API, to
the transport layer, following the Transport Services Architecture.
It supports the asynchronous, atomic transmission of messages over
transport protocols and network paths dynamically selected at
runtime.  It is intended to replace the traditional BSD sockets API
as the common interface to the transport layer, in an environment
where endpoints could select from multiple interfaces and potential
transport protocols.
Paragraph (version B):
This document describes an abstract application programming
interface, API, to the transport layer, following the Transport
Services Architecture.  It supports the asynchronous, atomic
transmission of messages over transport protocols and network paths
dynamically selected at runtime.  It is intended to replace the
traditional BSD sockets API as the common interface to the transport
layer, in an environment where endpoints could select from multiple
interfaces and potential transport protocols.
Draft: draft-ietf-taps-interface

Commentary: In the API doc sec 5 says . " Message Framers ( see Section 10 ) , if required , should be to the Preconnection during pre - establishment . " Should this be SHOULD or even MUST ? If SHOULD is correct I think we need to say slightly more about when it makes sense to add a framer later . 
 I think it should be " can be ... " ; not normative , just descriptive of fact . 
 Can we start with the " If ' perhaps ... " If messages frames are to be used , they MUST be to the Preconnection during pre - establishment . " ?
Paragraph (version A):
Message Framers (see framing), if required, should be added to the
Preconnection during pre-establishment.
Paragraph (version B):
If Message Framers are used (see framing), they MUST be added to the
Preconnection during pre-establishment.
Draft: draft-ietf-taps-impl

Commentary: As described in , I removed the condition that requires the application to specify the length upon receiving from this example . 
 Impl draft section 5.2 Receiving Messages : " if , on the other hand , the top - level protocol only supports a byte - stream and no deframers were supported , the application must specify the minimum number of bytes of Message content it wants to receive ( which may be just a single byte ) to control the flow of received data . " This text says the application MUST specify minIncompleteLength , however , the API draft says that this values is optional . This should be further clarified and more guidance given in case the value is not set . 
 Having looked at this and the API carefully , my suggestion would be to turn the semicolon preceding this statement into a full stop and remove all of this " if , on the other hand , .... " text in the implementation draft . 
 WFM . 
 This was a long text block - I had a few editorial NiTs you may like to address .
Paragraph (version A):
boundaries; if, on the other hand, the top-level protocol only
supports a byte-stream and no deframers were supported, the
application must specify the minimum number of bytes of Message
content it wants to receive (which may be just a single byte) to
control the flow of received data.
Paragraph (version B):
boundaries.  If the top-level protocol only supports a byte-stream
and no framers were supported, the application can control the flow
of received data by specifying the minimum number of bytes of Message
content it wants to receive at one time.
Draft: draft-ietf-taps-interface

Commentary: Would be nice if someone has time to do some ascii art :-) 
 Would n't that be fig . 4 in the architecture draft ? Except that , looking at this now , I see inconsistencies ! E.g. , I do n't see " RendezvousDone " in the figure . Also , instead of ConnectionReceived , it says " Connection Received " - rather , this should probably marked as an event by writing it as " ConnectionReceived < " . The figure is also missing InitiateWithSend ( ) ... probably it would be good to make this figure both complete and consistent with section 13 , " Connection State and Ordering of Operations and Events " , of the API draft ? I do n't think very much is missing there . 
 I think it would be nice to have a real state diagram here , probably with states like " closed " , " open " and " listen " and the events that create a transition between these state . 
 I 'm not sure that Figure 4 in the  diagram serves the purpose that  's trying to address with the state diagram in API . I also do n't think we need FIgure 4 to align with the specific naming and CamelCasingConventions in API . 
 Thanks ! I guess you could add a loop for sent < and received < in established state but maybe that also too much . Works for me
Paragraph (version B):
The following diagram shows the possible states of a Connection and
the events that occur upon a transition from one state to another.
Draft: draft-ietf-taps-arch

Commentary: Address 
 I think the word /assumes/ is not a good choice of word in the arch draft . OLD : and it assumes an implementation that can use multiple IP addresses , multiple protocols , multiple paths , and provide multiple application streams NEW : and it can provide benefit when an implementation can use multiple IP addresses , multiple protocols , multiple paths , and provide multiple application streams . 
 Done 
 Exactly what I expected to see !
Paragraph (version A):
This document describes an architecture for exposing transport
protocol features to applications for network communication, the
Transport Services architecture.  The Transport Services Application
Programming Interface (API) is based on an asynchronous, event-driven
interaction pattern.  It uses messages for representing data transfer
to applications, and it assumes an implementation that can use
multiple IP addresses, multiple protocols, and multiple paths, and
provide multiple application streams.  This document further defines
common terminology and concepts to be used in definitions of
Transport Services APIs and implementations.
Paragraph (version B):
This document describes an architecture for exposing transport
protocol features to applications for network communication, the
Transport Services architecture.  The Transport Services Application
Programming Interface (API) is based on an asynchronous, event-driven
interaction pattern.  It uses messages for representing data transfer
to applications, and it describes how implementations can use
multiple IP addresses, multiple protocols, and multiple paths, and
provide multiple application streams.  This document further defines
common terminology and concepts to be used in definitions of
Transport Services APIs and implementations.
Paragraph (version A):
There are key differences between the architecture of the Transport
Services system and the architecture of the Socket API: the Transport
Services API is asynchronous and event-driven; it uses messages for
representing data transfer to applications; and it assumes an
implementation that can use multiple IP addresses, multiple
protocols, multiple paths, and provide multiple application streams.
Paragraph (version B):
There are key differences between the architecture of the Transport
Services system and the architecture of the Socket API: the Transport
Services API is asynchronous and event-driven; it uses messages for
representing data transfer to applications; and it describes how
implementations can use multiple IP addresses, multiple protocols,
multiple paths, and provide multiple application streams.
Draft: draft-ietf-taps-interface

Commentary: I inserted the text that I quoted in this issue , with a minor tweak . 
 List discussion :  : 
 I agree with the conclusion of above - in which case we should leave things as they are . Other views ? 
 I agree that if the application does nothing then communication should be reliable . But I understand  's comment as asking about the relationship to the selection property Reliable Data Transfer ( Connection ) . If you for example set that to Avoid and the TAPS system selects SCTP as the protocol , then if you do not set Reliable Data Transfer ( Message ) on a message I assume it will be sent as an unreliable message . So in that sense the reliability of a message defaults to whatever is set for the connection , unless it is overridden by setting Reliable Data Transfer ( Message ) . And the default for Reliable Data Transfer ( Connection ) is  so what writes still holds but it is a different thing . 
 So if we agree upon Reliable Data Transfer ( Connection ) , then it would seem less confusing for Reliable Data Transfer ( Message ) - to use the same logic . Does an apps writer need to know the data will be sent as an unreliable message ? ( I 'm not sure I like " avoid reliable data transfer " as a meaningful concatenation of keywords BTW:- ) . 
 Let 's see what needs to be done . Suggestion : the only textual change would be to add the following , at the beginning of Section 7.5 , just before " The following Message Properties are supported " : " Connection Properties describe the default behavior for all Messages on a Connection . If a Message Property contradicts a Connection Property , it overrides the Connection Property for the specific Message . For example , if " Reliable Data Transfer ( Connection ) " is set to " Avoid " and a protocol with configurable per - Message reliability is used , setting " Reliable Data Transfer ( Message ) " to " Prefer " for a particular Message will ensure that this Message is reliably delivered . If the underlying protocol can not support this per - Message behavior , this Message Property choice will yield an error . " 
 Thanks ! No more comments now :)
Paragraph (version B):
Connection Properties describe the default behavior for all Messages
on a Connection.  If a Message Property contradicts a Connection
Property, and if this per-Message behavior can be supported, it
overrides the Connection Property for the specific Message.  For
example, if "Reliable Data Transfer (Connection)" is set to "Require"
and a protocol with configurable per-Message reliability is used,
setting "Reliable Data Transfer (Message)" to "false" for a
particular Message will allow this Message to be unreliably
delivered.  Note that changing the Reliable Data Transfer property on
Messages is only possible for Connections that were established with
the Selection Property "Configure Per-Message Reliability" enabled.
Draft: draft-ietf-taps-interface

Commentary: I chose boolean , because , when querying , it only matters whether a Selection Property was chosen or not ( I believe ) . 
 From   : says : I think this is n't very controversial , I believe we should just do this as he suggested . This issue is just a reminder for myself to do this . 
 Thanks
Paragraph (version A):
Preference: can take one of five values (Prohibit, Avoid, Ignore,
Prefer, Require) for the level of preference of a given property
during protocol selection; see selection-props.
Paragraph (version B):
Preference: can take one of five values (Prohibit, Avoid, Ignore,
Prefer, Require) for the level of preference of a given property
during protocol selection; see selection-props.  When querying, a
Preference is of type Boolean, with "true" indicating that the
Selection Property has been applied.
Paragraph (version A):
connection-props provides a list of Connection Properties, while
Selection Properties are listed in the subsections below.  Note that
many properties are only considered during establishment, and can not
be changed after a Connection is established; however, they can be
queried.  Querying a Selection Property after establishment yields
the value "Require" for properties of the selected protocol and path,
Avoid for properties avoided during selection, and Ignore for all
other properties.
Paragraph (version B):
connection-props provides a list of Connection Properties, while
Selection Properties are listed in the subsections below.  Note that
many properties are only considered during establishment, and can not
be changed after a Connection is established; however, they can be
queried.  The return type of a queried Selection Property is Boolean,
where "true" means that the Selection Property has been applied and
"false" means that the Selection Property has not been applied.  Note
that "true" does not mean that a request has been honored.  For
example, if "Congestion control" was requested with preference level
"Prefer", but congestion control could not be supported, querying the
"congestionControl" property yields the value "false".  If preference
level "Avoid" was used for "Congestion control", and, as requested,
the Connection is not congestion controlled, querying the
"congestionControl" property also yields the value "false".
Draft: draft-ietf-taps-interface

Commentary: ... as suggested by 
 The section on partial send says : " All data sent with the same MessageContext object will be treated as belonging to the same Message , and will constitute an in - order series until the endOfMessage is marked . Once the end of the Message is marked , the MessageContext object may be re - used as a new Message with identical parameters . " Can we reconsider for a second if that is really the way we want to design this ? This is really implicit and therefore an easy source for errors . I guess we could alternatively use an explicit message identifier ... ? Or the send action always return an identifier and for subsequent sends we input this identifier again ? Or someone has a smarter idea ? 
 I do n't have my head buried in code like some others here ( , .. ) , so I guess that these folks should speak up - but just from reading this , I agree that the current design sounds like an easy source for errors . 
 I 'd prefer to just remove the part that mentions reusing the same object . That 's an implementation detail ( and a perf optimization ) . The rest seems correct .
Paragraph (version A):
All data sent with the same MessageContext object will be treated as
belonging to the same Message, and will constitute an in-order series
until the endOfMessage is marked.  Once the end of the Message is
marked, the MessageContext object may be re-used as a new Message
with identical parameters.
Paragraph (version B):
All data sent with the same MessageContext object will be treated as
belonging to the same Message, and will constitute an in-order series
until the endOfMessage is marked.
Draft: draft-ietf-taps-impl

Commentary: Mainly adding references to arch and API docs ...
Paragraph (version B):
I-D.ietf-taps-arch outlines general security consideration and
requirements for any system that implements the TAPS archtecture.  I-
D.ietf-taps-interface provides further discussion on security and
privacy implications of the TAPS API.  This document provides
additional guidance on implementation specifics for the TAPS API and
as such the security considerations in both of these documents apply.
The next two subsections discuss further considerations that are
specific to mechanisms specified in this document.