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

Commentary: Fixed text in the API draft to allow reusing Preconnections as discussed in . However , changes to the Preconnection MUST NOT have any effect on the Connections or Listeners created beforehand - I think normative language is useful here to really highlight this possible pitfall . I omitted any note on deep copy as that 's just a way to implement this . 
 Great catch , it makes me wonder why we had closed issue ? Thanks for doing this!Thank you - fix achieved with minimal changes ;-)
Paragraph (version A):
The Initiate() Action consumes the Preconnection.  Once Initiate()
has been called, no further properties may be added to the
Preconnection, and no subsequent establishment call may be made on
the Preconnection.
Paragraph (version B):
The Initiate() Action returns a Connection object.  Once Initiate()
has been called, any changes to the Preconnection MUST NOT have any
effect on the Connection.  However, the Preconnection can be reused,
e.g., to Initiate another Connection.
Paragraph (version A):
Before calling Listen, the caller must have initialized the
Preconnection during the pre-establishment phase with a Local
Endpoint specifier, as well as all properties necessary for Protocol
Stack selection.  A Remote Endpoint may optionally be specified, to
constrain what Connections are accepted.  The Listen() Action returns
a Listener object.  Once Listen() has been called, properties added
to the Preconnection have no effect on the Listener and the
Preconnection can be disposed of or reused.
Paragraph (version B):
Before calling Listen, the caller must have initialized the
Preconnection during the pre-establishment phase with a Local
Endpoint specifier, as well as all properties necessary for Protocol
Stack selection.  A Remote Endpoint may optionally be specified, to
constrain what Connections are accepted.
Paragraph (version B):
The Listen() Action returns a Listener object.  Once Listen() has
been called, any changes to the Preconnection MUST NOT have any
effect on the Listener.  The Preconnection can be disposed of or
reused, e.g., to create another Listener.
Paragraph (version A):
The Rendezvous() Action consumes the Preconnection.  Once
Rendezvous() has been called, no further properties may be added to
the Preconnection, and no subsequent establishment call may be made
on the Preconnection.
Paragraph (version B):
The Rendezvous() Action returns a Connection object.  Once
Rendezvous() has been called, any changes to the Preconnection MUST
NOT have any effect on the Connection.  However, the Preconnection
can be reused, e.g., for Rendezvous of another Connection.
Draft: draft-ietf-taps-arch

Commentary: Proposed some text for - I think this summarizes the " flexibility " advantage of TAPS that we elaborate on in Section 2.3 . 
 In Section 1.2 , Overview , the architecture draft says that TAPS offers " the ability to easily adopt different transport protocols " . What does " adopt " mean here ? I guess this relates to Section 2.3 ( maybe say that explicitly here ) , but even after reading this Section , I do n't quite understand why " adopt " . Is the point here that a flexible interface makes it easier to add support for new protocols ? Then perhaps we should say this here . 
 It means that applications do n't need to rewrite a ton of code or adopt a new library to access a new transport protocol . In how I read it , " adopt " captures that , but if there 's some other text you would like to suggest , that 's fine . 
 For me " adopt " is fine as it should be clear from the rest of the doc . However , if we want to be more clear we could say " make use of different protocols without the need to change the interface " or something ... ? 
 Looks good , merged !
Paragraph (version A):
model describes how the API model of Transport Services differs
from traditional socket-based APIs.  Specifically, it offers
asynchronous event-driven interaction, the use of messages for
data transfer, and the ability to easily adopt different transport
protocols.
Paragraph (version B):
model describes how the API model of Transport Services differs
from traditional socket-based APIs.  Specifically, it offers
asynchronous event-driven interaction, the use of messages for
data transfer, and the flexibility to use different transport
protocols and paths without requiring major changes to the
application.
Draft: draft-ietf-taps-arch

Commentary: Following , Section 4.2.3 of the Architecture document now says that fallback between different security protocol versions might be allowed . The Security Considerations section was out of sync . This PR fixes that .
Paragraph (version A):
As described above in equivalence, if a Transport Services system
races between two different Protocol Stacks, both MUST use the same
security protocols and options.
Paragraph (version B):
As described above in equivalence, if a Transport Services system
races between two different Protocol Stacks, both SHOULD use the same
security protocols and options.  However, a Transport Services system
MAY race different security protocols, e.g., if the application
explicitly specifies that it considers them equivalent.
Paragraph (version B):
Moreover, Transport Services systems MUST NOT automatically fall back
from secure protocols to insecure protocols, or to weaker versions of
secure protocols.  For example, if an application requests a specific
version of TLS, but the desired version of TLS is not available, its
connection will fail.  Applications are thus responsible for
implementing security protocol fallback or version fallback by
creating multiple Transport Services Connections, if so desired.
Draft: draft-ietf-taps-interface

Commentary: Btw . does this cover all events ? There is an issue where I also ask if we e.g. need an event that sending failed due to lifetime  . is there a way to double - check if we considered all needed events ? Should we also mention ConnectionErrors here ? Maybe we anyway need to say more about error ? 
 These are not all events ( just search for the word " event " in the document ) , and generally they are not all lumped together - e.g. sending related events such as " Sent " appear in the " Sending Data " section - which , in fact , has its own subsection called " Send Events " . So , this would be a subsection just related to connection management ... but then , you state : " During the lifetime of a connection there are events that can occur when configured . " which gives the ( wrong ) impression that this would be the list of all events that can happen during a connection 's lifetime . So , I would n't add this subsection heading and not include that statement . Or maybe add the subsection heading ( which is ok but does n't help much - as you see , there are only very few events in there ) , but remove that statement . 
 +1 to calling this " connection lifecycle events " or similar ( do we refer to a connection lifecycle ? ) 
 Changed the heading and fixed the nit . I 'm open to have another sentence there if people have proposals . We could even have no text but we usually say something after each heading . 
 Given the new heading , I 'm fine with the sentence as it is - because the context is clear now , it 's no longer misleading ( i.e. , giving the wrong impression that these would be ALL events ) .
Paragraph (version B):
During the lifetime of a connection there are events that can occur
when configured.
Draft: draft-ietf-taps-interface

Commentary: Comma in the first section was wrong but better to rephrase anyway ... 
 nit
Paragraph (version A):
The Connection Properties defined as independent of the chosen
protocol stack, and available on all Connections are defined in the
subsections below.
Paragraph (version A):
Note that many Connection Properties have a corresponding Selection
Property, which enables applications to express their preference for
protocols providing a supporting transport feature.
Paragraph (version B):
Generic Connection Properties are defined independent of the chosen
protocol stack and therefore available on all Connections.
Paragraph (version B):
Note that many Connection Properties have a corresponding Selection
Property which enables applications to express their preference for
protocols providing a supporting transport feature.
Draft: draft-ietf-taps-interface

Commentary: I 'm not quite sure what I meant by " Only full coverage is guaranteed , any other requests are advisory " . I assume we mean that even if a partial checksum is requested you get full coverage because requesting partial coverage and getting no checksum does n't seem right ... ? 
 Exactly , and you made it clearer . Thanks !
Paragraph (version A):
This property specifies the minimum length of the section of the
Message, starting from byte 0, that the application requires to be
delivered without corruption due to lower layer errors.  It is used
to specify options for simple integrity protection via checksums.  A
value of 0 means that no checksum is required, and -1 means that the
entire Message is protected by a checksum.  Only full coverage is
guaranteed, any other requests are advisory.
Paragraph (version B):
This property specifies the minimum length of the section of the
Message, starting from byte 0, that the application requires to be
delivered without corruption due to lower layer errors.  It is used
to specify options for simple integrity protection via checksums.  A
value of 0 means that no checksum is required, and -1 means that the
entire Message is protected by a checksum.  Only full coverage is
guaranteed, any other requests are advisory, meaning that full
coverage is applied anyway.
Draft: draft-ietf-taps-interface

Commentary: Just a proposal ... 
 Well , you could do it with streams in SCTP as well so as an example it seems approriate . And good with an example I think . 
 Yes , we do have actually these kind of examples in many cases in the doc and I just thought when reading one could help here as well . 
 I do n't understand why one would need streams for this in SCTP , but it does n't matter . As I said I have no strong opinion , I 'm fine with adding this example ( and I just fixed the nit ) . 
 you do not need to , as there are multiple ways to do it in SCTP , but you could .
Paragraph (version A):
If true, it specifies that the receiver-side transport protocol stack
may only deliver the Message to the receiving application after the
previous ordered Message which was passed to the same Connection via
the Send Action, when such a Message exists.  If false, the Message
may be delivered to the receiving application out of order.  This
property is used for protocols that support preservation of data
ordering, see prop-ordering, but allow out-of-order delivery for
certain messages.
Paragraph (version B):
If true, it specifies that the receiver-side transport protocol stack
may only deliver the Message to the receiving application after the
previous ordered Message which was passed to the same Connection via
the Send Action, when such a Message exists.  If false, the Message
may be delivered to the receiving application out of order.  This
property is used for protocols that support preservation of data
ordering, see prop-ordering, but allow out-of-order delivery for
certain messages, e.g., by multiplexing independent messages onto
different streams.
Draft: draft-ietf-taps-interface

Commentary: Done 
 good to go as it is , IMO
Paragraph (version B):
Framers can be used to extend or modify the message data with
additional information that can be processed at the receiver to
detect message boundaries.  This is further decribed in framing.
Draft: draft-ietf-taps-interface

Commentary: Agree , they 're definitely objects . While an implementation might choose to implement different types of endpoint identifiers as subtypes of such objects , we do n't want to be that specific here . LGTM
Paragraph (version A):
The transport services API uses the Local Endpoint and Remote
Endpoint types to refer to the endpoints of a transport connection.
Subtypes of these represent various different types of endpoint
identifiers, such as IP addresses, DNS names, and interface names, as
well as port numbers and service names.
Paragraph (version B):
The transport services API uses the Local Endpoint and Remote
Endpoint Objects to refer to the endpoints of a transport connection.
Actions on these Objects can be used to represent various different
types of endpoint identifiers, such as IP addresses, DNS names, and
interface names, as well as port numbers and service names.
Draft: draft-ietf-taps-interface

Commentary: It looks like we should use normative language here . We could also use the keywords of the IANA protocol number registry to indicate reserved namespaces for IETF protocols ( that can not be used in the vendor or implementation specific namespaces anyway ) . See 
 Like this ? 
 This is great , thanks !
Paragraph (version A):
The Namespace part is empty for well known, generic properties,
i.e., for properties that are not specific to a protocol and are
defined in an RFC.
Paragraph (version B):
The Namespace part MUST be empty for well-known, generic
properties, i.e., for properties that are not specific to a
protocol and are defined in an RFC.
Paragraph (version B):
Namespaces for the keywords provided in the IANA protocol numbers
registry (see https://www.iana.org/assignments/protocol-numbers/
protocol-numbers.xhtml) are reserved for Protocol Specific Properties
and MUST not be used for vendor or implementation specific
properties.
Draft: draft-ietf-taps-interface

Commentary: The term Protocol Specific Properties is not well introduced . In the  doc we have a section about " Specialized Features " and I not a reference and rephrased the sentence respectively . Do we need to say more than that ? 
 LGTM modulo two nitsLooks good to me , except one nit .
Paragraph (version A):
Note that Configuring Connection Properties and Message Properties on
Preconnections is preferred over setting them later.  Early
specification of Connection Properties allows their use as additional
input to the selection process.  Protocol Specific Properties, see
property-names, should not be used as an input to the selection
process.
Paragraph (version B):
Note that configuring Connection Properties and Message Properties on
Preconnections is preferred over setting them later.  Early
specification of Connection Properties allows their use as additional
input to the selection process.  Protocol Specific Properties, which
enable configuration of specialized features of a specific protocol,
see Section 3.2 of I-D.ietf-taps-arch, are not used as an input to
the selection process but only support configuration if the
respective prototocol has been selected.
Draft: draft-ietf-taps-interface

Commentary: LGTM modulo a super tiny nit
Paragraph (version A):
pre-establishment, establishment, sending, receiving, and termination
describe the details of application interaction with Objects through
Actions and Events in each phase of a Connection, following the
phases described in I-D.ietf-taps-arch.
Paragraph (version B):
pre-establishment, establishment, sending, receiving, and termination
describe the details of application interaction with Objects through
Actions and Events in each phase of a Connection, following the
phases (Pre-Establishment, Establishment, Data Transfer, and
Termination) described in Section 4.1 of I-D.ietf-taps-arch.
Draft: draft-ietf-taps-interface

Commentary: s / messages can be sent / messages can be sent and received/
Paragraph (version A):
Once a Connection is established, data can be sent on it in the form
of Messages.  The interface supports the preservation of message
boundaries both via explicit Protocol Stack support, and via
application support through a Message Framer which finds message
boundaries in a stream.  Messages are received asynchronously through
event handlers registered by the application.  Errors and other
notifications also happen asynchronously on the Connection.
Paragraph (version B):
Once a Connection is established, data can be sent and received on it
in the form of Messages.  The interface supports the preservation of
message boundaries both via explicit Protocol Stack support, and via
application support through a Message Framer which finds message
boundaries in a stream.  Messages are received asynchronously through
event handlers registered by the application.  Errors and other
notifications also happen asynchronously on the Connection.
Draft: draft-ietf-taps-arch

Commentary: " within a message " twice in the same sentence 
 Thanks !
Paragraph (version A):
Message: A Message object is a unit of data that can be
represented as bytes that can be transferred between two systems
over a transport connection.  The bytes within a Message are
assumed to be ordered within the Message.  If an application does
not care about the order in which a peer receives two distinct
spans of bytes, those spans of bytes are considered independent
Messages.
Paragraph (version B):
Message: A Message object is a unit of data that can be
represented as bytes that can be transferred between two systems
over a transport connection.  The bytes within a Message are
assumed to be ordered.  If an application does not care about the
order in which a peer receives two distinct spans of bytes, those
spans of bytes are considered independent Messages.
Draft: draft-ietf-taps-arch

Commentary: Just a proposal ... 
 Thanks!Thanks
Paragraph (version A):
Transport Services implementations are meant to be flexible at
connection establishment time, considering many different options and
trying to select the most optimal combinations (gathering and
racing).  This requires applications to provide higher-level
endpoints than IP addresses, such as hostnames and URLs, which are
used by a Transport Services implementation for resolution, path
selection, and racing.
Paragraph (version B):
Transport Services implementations are meant to be flexible at
connection establishment time, considering many different options and
trying to select the most optimal combinations (gathering and
racing).  This requires applications to provide higher-level
endpoints than IP addresses, such as hostnames and URLs, which are
used by a Transport Services implementation for resolution, path
selection, and racing.  Transport services implementations can
further implement fallback mechanisms if connection establishment of
one protocol fails or performance is detected to be unsatisfactory.
Draft: draft-ietf-taps-interface

Commentary: When reading the API draft , I noticed that in some places it was still using the outdated term " Protocol Properties " where it actually means Connection Properties or Message Properties . I replaced the terms in this PR . We do still define " Specific Protocol Properties " , so I kept these .
Paragraph (version A):
Calling Clone on a Connection yields a group of two Connections: the
parent Connection on which Clone was called, and the resulting cloned
Connection.  These connections are "entangled" with each other, and
become part of a Connection Group.  Calling Clone on any of these two
Connections adds a third Connection to the Connection Group, and so
on.  Connections in a Connection Group share all Protocol Properties
that are not applicable to a Message.
Paragraph (version A):
Changing one of these Protocol Properties on one Connection in the
group changes it for all others.  Per-Message Protocol Properties,
however, are not entangled.  For example, changing "Timeout for
aborting Connection" (see conn-timeout) on one Connection in a group
will automatically change this Protocol Property for all Connections
in the group in the same way.  However, changing "Lifetime" (see msg-
lifetime) of a Message will only affect a single Message on a single
Connection, entangled or not.
Paragraph (version B):
Calling Clone on a Connection yields a group of two Connections: the
parent Connection on which Clone was called, and the resulting cloned
Connection.  These connections are "entangled" with each other, and
become part of a Connection Group.  Calling Clone on any of these two
Connections adds a third Connection to the Connection Group, and so
on.  Connections in a Connection Group generally share Connection
Properties.  However, there may be exceptions, such as "Priority
(Connection)", see conn-priority.
Paragraph (version B):
Changing one of the Connection Properties on one Connection in the
group changes it for all others.  Message Properties, however, are
not entangled.  For example, changing "Timeout for aborting
Connection" (see conn-timeout) on one Connection in a group will
automatically change this Connection Property for all Connections in
the group in the same way.  However, changing "Lifetime" (see msg-
lifetime) of a Message will only affect a single Message on a single
Connection, entangled or not.
Paragraph (version A):
The Connection Properties defined as independent, and available on
all Connections are defined in the subsections below.
Paragraph (version A):
Note that many protocol properties have a corresponding selection
property, which prefers protocols providing a supporting transport
feature.
Paragraph (version B):
The Connection Properties defined as independent of the chosen
protocol stack, and available on all Connections are defined in the
subsections below.
Paragraph (version B):
Note that many Connection Properties have a corresponding Selection
Property, which enables applications to express their preference for
protocols providing a supporting transport feature.
Draft: draft-ietf-taps-interface

Commentary: Add a reference to MPS in DPLPMTUD for the Message Size Before Fragmentation property . 
 LGMT , just replace " models " with something more suitable .
Paragraph (version A):
This property, if applicable, represents the maximum Message size
that can be sent without incurring network-layer fragmentation or
transport layer segmentation at the sender.
Paragraph (version B):
This property, if applicable, represents the maximum Message size
that can be sent without incurring network-layer fragmentation or
transport layer segmentation at the sender.  This property exposes
the Maximum Packet Size (MPS) as described in Datagram PLPMTUD I-
D.ietf-tsvwg-datagram-plpmtud.