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

Commentary: The text says What does disabling mean ? Does this mean mean that it is valid to set this property to " Prohibit " but still set " safelyReplayable " to " Require " on the PreConnection . Should that not be an error ? This is also related to . The use of safelyReplayable for both reliable and unreliable services makes the text a bit confusing . Would it not be sufficient to state that if you do not  Reliable Data Transfer you have to be prepared to deal with duplication ? 
 We should remove this sentence in 4.2.5 :
Paragraph (version A):
This property specifies whether an application would like to supply a
Message to the transport protocol before Connection establishment
that will then be reliably transferred to the other side before or
during Connection establishment.  This Message can potentially be
received multiple times (i.e., multiple copies of the message data
may be passed to the Remote Endpoint).  See also msg-
safelyreplayable.  Note that disabling this property has no effect
for protocols that are not connection-oriented and do not protect
against duplicated messages, e.g., UDP.
Paragraph (version B):
This property specifies whether an application would like to supply a
Message to the transport protocol before Connection establishment
that will then be reliably transferred to the other side before or
during Connection establishment.  This Message can potentially be
received multiple times (i.e., multiple copies of the message data
may be passed to the Remote Endpoint).  See also msg-
safelyreplayable.
Draft: draft-ietf-taps-interface

Commentary: The text reads quire off when it says a priority property represents a hierarchy of priorities : This property represents a hierarchy of priorities . Could this better be : ‘ A priority property is organised within a hierarchy of priorities . ‘ ? 
 When reading " hierarchy " , it 's easy to think that there may be priority sub - groups within priority groups , or something of that nature . Yet , this is not the case , it 's just a flat priority assignment . Hence , to me , mentioning " hierarchy " here is misleading altogether . Therefore , I think we 'd be much better off removing this sentence , i.e. replacing : with 
 Seems to resolving the odd wording .
Paragraph (version A):
This property represents a hierarchy of priorities.  It can specify
the priority of a Message, relative to other Messages sent over the
same Connection.
Paragraph (version B):
This property specifies the priority of a Message, relative to other
Messages sent over the same Connection.
Draft: draft-ietf-taps-interface

Commentary: Section 7.2.6 . says " for example , if a transport stack that only provides a single in - order reliable stream is selected , prioritization information can only be ignored . " I do n't think this is entirely true as you can still decide in which order you schedule independent messages on one stream . 
 I do n't get this . The sentence says " in - order " . Scheduling them from buffer A into buffer B in accordance with priorities wo n't help when everything leaves buffer B in a fixed sequence . 
 How about a less complex sentence : ... " for example , if the transport system selects a stack that only provides a single in - order reliable stream , the prioritization information is ignored . " 
 message on the taps " layer " are independent . so the order an application calls send on these message does n't have to be the same order the messages are send on an " in - order stream " 
 Oh , now I see what you mean . Hmmm ... looking at the text , it seems that we could just delete this sentence and the problem is solved ? 
 I think what was intended with the example was to show that the set priorities may not have any effect . Perhaps we should instead just add " and the set priorities may not have any effect " if we want to be explicit ? Removing it also works though . 
 I think just add that ! 
 I 'm for removing it ( I think I wrote this sentence btw :-) ) . Giving this example just throws off someone who thinks about this case like  did here - even if we say " may not apply " , the reader may ( correctly ) think " but why , in this case they CAN well apply ! " . So I do n't find that helpful . For context , the full current statement is : and I believe that we say everything we need to say if we just change this into : 
 I like simple examples , this one was n't great so this is OK .
Paragraph (version A):
A Transport Services system gives no guarantees about how its
expression of relative priorities will be realized; for example, if a
transport stack that only provides a single in-order reliable stream
is selected, prioritization information can only be ignored.
However, the Transport Services system will seek to ensure that
performance of relatively-prioritized connections and messages is not
worse with respect to those connections and messages than an
equivalent configuration in which all prioritization properties are
left at their defaults.
Paragraph (version B):
A Transport Services system gives no guarantees about how its
expression of relative priorities will be realized.  However, the
Transport Services system will seek to ensure that performance of
relatively-prioritized connections and messages is not worse with
respect to those connections and messages than an equivalent
configuration in which all prioritization properties are left at
their defaults.
Draft: draft-ietf-taps-impl

Commentary: Addition to clarify what happens when a transport system replays messages - 
 The current text says : If true , Safely Replayable specifies that a Message is safe to send to the Remote Endpoint more than once for a single Send Action . It marks the data as safe for certain 0 - RTT establishment techniques , where retransmission of the 0 - RTT data may cause the remote application to receive the Message multiple times . For protocols that do not protect against duplicated messages , e.g. , UDP , all messages need to be marked as " Safely Replayable " . To enable protocol selection to choose such a protocol , " Safely Replayable " needs to be to the TransportProperties passed to the Preconnection . If such a protocol was chosen , disabling " Safely Replayable " on individual messages MUST result in a SendError . — I think this could perhaps be misleading , and suggest : 1 . I would like to change /UDP / directly over UDP/ .... because clearly it is possible that a transport such as QUIC also uses UDP , but provides this sort of protection above the UDP layer . 2 . This is still written from the perspective of the protocol . I think it is important here to also therefore add a sentence then clarifies that the application might be able to designed to detect and ignore such duplication . ‘ Protection from replay of messages could be provided by an application when a transport system replays messages ’ .
Paragraph (version A):
Safely Replayable: when this is true, this means that the Message
can be used by mechanisms that might transfer it multiple times -
e.g., as a result of racing multiple transports or as part of TCP
Fast Open.  Also, protocols that do not protect against duplicated
messages, such as UDP, can only be used with Messages that are
Safely Replayable.
Paragraph (version B):
Safely Replayable: when this is true, this means that the Message
can be used by a transport mechanism that might transfer it
multiple times - e.g., as a result of racing multiple transports
or as part of TCP Fast Open.  Also, protocols that do not protect
against duplicated messages, such as UDP (when used directly,
without a protocol layered atop), can only be used with Messages
that are Safely Replayable.  When a transport system is permitted
to replay messages, replay protection could be provided by the
application.
Draft: draft-ietf-taps-interface

Commentary: To address NiTs 
 I - D.ietf - tsvwg - datagram - plpmtud is now a RFC . 
 See PR 
 Resolved in PR 
 The current text says : Constant - Rate Streaming : The application expects to send / receive data at a constant rate after Connection establishment . Delay and delay variation should be minimized at the expense of efficient use of the available capacity . This implies that the Connection might fail if the desired rate can not be maintained across the Path . this last sentence sounds a little like the app needs to maintain the rate , rather than the path is expected to offer the rate . Could we change the last sentence to : /This implies that the Connection might fail if the Path is unable to maintain the desired rate . / 
 See PR 
 This was fixed in PR 
 Editorial : This text at the end of the intro reads odd to me : ‘ This specific transport stack choice is discouraged for general use , because it can reduce the portability . ’ I think it should read more like : ‘ This choice , which only permits using a specific transport stack is discouraged for general use , because it can reduce the portability . ’ — — Editorial ; Is a Connection an instance of the stack ? The current text says : ‘ A Connection represents a transport   on which data can be sent to and/or received from a Remote Endpoint ’ This may be better as ? : ‘ A Connection represents an instance if a transport   on which data can be sent to and/or received from a Remote Endpoint ’ — — ‘ Editorial ‘ through a Message Framer which finds message ’ Should this be : ‘ through a Message Framer that finds message ’ 
 See PR 
 Resolved in PR 
 This LGTM , thanks !
Paragraph (version A):
The application expects to send/receive data at a constant rate
after Connection establishment.  Delay and delay variation should
be minimized at the expense of efficient use of the available
capacity.  This implies that the Connection might fail if the
desired rate cannot be maintained across the Path.  A transport
can interpret this capacity profile as preferring a circuit
breaker RFC8084 to a rate-adaptive congestion controller.
Transport system implementations that map the requested capacity
profile onto per-connection DSCP signaling without multiplexing
SHOULD assign a DSCP Assured Forwarding (AF31,AF32,AF33,AF34)
RFC2597 PHB.
Paragraph (version B):
The application expects to send/receive data at a constant rate
after Connection establishment.  Delay and delay variation should
be minimized at the expense of efficient use of the available
capacity.  This implies that the Connection might fail if the Path
is unable to maintain the desired rate.  A transport can interpret
this capacity profile as preferring a circuit breaker RFC8084 to a
rate-adaptive congestion controller.  Transport system
implementations that map the requested capacity profile onto per-
connection DSCP signaling without multiplexing SHOULD assign a
DSCP Assured Forwarding (AF31,AF32,AF33,AF34) RFC2597 PHB.
Draft: draft-ietf-taps-interface

Commentary: Clarify that the Connection returned by Clone will send a Ready Event or an InitiateError Event . 
 Clone ( ) is analogous to Initiate ( ) , so why does n't it return ready events like initiate ( ) ? 
 This should be OK because Initiate does n't generate the Ready event , etc , but the Connection does . Both Initiate and Clone return a Connection . We can try to clarify this .
Paragraph (version A):
Calling Clone on a Connection yields a group of Connections: the
parent Connection on which Clone was called, and a resulting cloned
Connection.  The connections within a group are "entangled" with each
other, and become part of a Connection Group.  Calling Clone on any
of these Connections adds another Connection to the Connection Group,
and so on.  "Entangled" Connections share all Connection Properties
except "Connection Priority" (see conn-priority) .  Like all other
Properties, Connection Priority is copied to the new Connection when
calling Clone(), but it is not entangled: Changing Connection
Priority on one Connection does not change it on the other
Connections in the same Connection Group.
Paragraph (version B):
Calling Clone on a Connection yields a group of Connections: the
parent Connection on which Clone was called, and a resulting cloned
Connection.  The new Connection is actively openend, and it will send
a Ready Event or an EstablishmentError Event.  The Connections within
a group are "entangled" with each other, and become part of a
Connection Group.  Calling Clone on any of these Connections adds
another Connection to the Connection Group, and so on.  "Entangled"
Connections share all Connection Properties except "Connection
Priority" (see conn-priority) .  Like all other Properties,
Connection Priority is copied to the new Connection when calling
Clone(), but it is not entangled: Changing Connection Priority on one
Connection does not change it on the other Connections in the same
Connection Group.
Draft: draft-ietf-taps-impl

Commentary: explained the " deep - copy " term .
Paragraph (version A):
Preconnection objects should be implemented as bundles of properties
that an application can both read and write.  Once a Preconnection
has been used to create an outbound Connection or a Listener, the
implementation should ensure that the copy of the properties held by
the Connection or Listener is immutable.  This may involve performing
a deep-copy if the application is still able to modify properties on
the original Preconnection object.
Paragraph (version B):
Preconnection objects should be implemented as bundles of properties
that an application can both read and write.  Once a Preconnection
has been used to create an outbound Connection or a Listener, the
implementation should ensure that the copy of the properties held by
the Connection or Listener is immutable.  This may involve performing
a deep-copy, copying the object with all the objects it references,
if the application is still able to modify properties on the original
Preconnection object.
Draft: draft-ietf-taps-impl

Commentary: Now I feel like I 'm shaving the yak . This is more than what we talked about in the interim , but it felt like the following sentence required additional clarity . Let me know if I misunderstood the intended meaning , in which case I will rephrase .
Paragraph (version A):
Protocols that provide the framing (such as length-value protocols,
or protocols that use delimiters) provide data boundaries that may be
longer than the typical datagram.  Each Message for framing protocols
corresponds to a single frame, which may be sent either as a complete
Message, or in multiple parts.
Paragraph (version B):
Protocols that provide the framing (such as length-value protocols,
or protocols that use delimiters) may support Message sizes that do
not fit within a single datagram.  Each Message for framing protocols
corresponds to a single frame, which may be sent either as a complete
Message in the underlying protocol, or in multiple parts.
Draft: draft-ietf-taps-impl

Commentary: I stared at this sentence for a while before I thought I 'd made sense of it . PR forthcoming but I think this might need a little discussion . 
 lgtm
Paragraph (version A):
The application should be notified whenever a Message or partial
Message has been consumed by the Protocol Stack, or has failed to
send.  The meaning of the Message being consumed by the stack may
vary depending on the protocol.  For a basic datagram protocol like
UDP, this may correspond to the time when the packet is sent into the
interface driver.  For a protocol that buffers data in queues, like
TCP, this may correspond to when the data has entered the send
buffer.
Paragraph (version B):
The application should be notified whenever a Message or partial
Message has been consumed by the Protocol Stack, or has failed to
send.  The time at which a Message is considered to have been
consumed by the Protocol Stack may vary depending on the protocol.
For example, for a basic datagram protocol like UDP, this may
correspond to the time when the packet is sent into the interface
driver.  For a protocol that buffers data in queues, like TCP, this
may correspond to when the data has entered the send buffer.  The
time at which a message has failed to send is after the Protocol
Stack or the Transport Services implementation itself has not
successfully sent the entire Message content or partial Message
content on any open candidate connection; this may depend on
protocol-specific timeouts.
Draft: draft-ietf-taps-impl

Commentary: Oh yes , and it IS editorial ! :-D 
 Is " racing " really the right term ? It might be a term of art that applies even in cases like this , but many of the relationships between different branches in the tree are based on preference rather than lowest latency . I do n't feel strongly about this , but I do n't know if this has been brought up yet , so I figured I 'd mention it . 
 I agree that it may seem a bit misleading , but I think it 's ok - it 's just the word we use for it , and the term and how we use it is quite clearly defined in the Architecture draft , section 4.2.2 . Just my 2c 
 I like " racing " - it 's just a term .... 
 Racing is defined in the architecture document ; add a reference back there . 
 Thanks for fixing this !
Paragraph (version A):
Connection establishment is divided into two top-level steps:
Candidate Gathering, to identify the paths, protocols, and endpoints
to use, and Candidate Racing, in which the necessary protocol
handshakes are conducted so that the transport system can select
which set to use.  This document structures candidates for racing as
a tree.
Paragraph (version B):
Connection establishment is divided into two top-level steps:
Candidate Gathering, to identify the paths, protocols, and endpoints
to use, and Candidate Racing (see Section 4.2.2 of I-D.ietf-taps-
arch), in which the necessary protocol handshakes are conducted so
that the transport system can select which set to use.  This document
structures candidates for racing as a tree.
Draft: draft-ietf-taps-impl

Commentary: Section 4.2.2 says " If a child node fails to connect before ... " without really defining if this means completing the handshake , or making some progress . 4.3.1 does a better job , but for readability there ought to be a reference or rewording in 4.2.2 . 
 /to connect/ is problematic for me also , but /establish  is less problematic , although always good to explain !
Paragraph (version A):
If a child node fails to connect before the delay time has expired
for the next child, the next child should be started immediately.
Paragraph (version B):
If a child node fails to establish connectivity (as in determining-
successful-establishment) before the delay time has expired for the
next child, the next child should be started immediately.
Draft: draft-ietf-taps-impl

Commentary: Provide examples of why we do n't tear down path changes
Paragraph (version B):
There are many common user scenarios that can lead to a path becoming
temporarily unavailable, and then recovering before the transport
protocol reaches a timeout error.  These are particularly common
using mobile devices.  Examples include: an Ethernet cable becoming
unplugged and then plugged back in; a device losing a Wi-Fi signal
while a user is in an elevator, and reattaching when the user leaves
the elevator; and a user losing the radio signal while riding a train
through a tunnel.  If the device is able to rejoin a network with the
same IP address, a stateful transport connection can generally
resume.  Thus, while it is useful for a Protocol Instance to be aware
of a temporary loss of connectivity, the Transport Services
implementation should not aggressively close connections in these
scenarios.
Draft: draft-ietf-taps-interface

Commentary: Should taps - interface provide a way to close a connection group ? I do n't see an obvious way to close an HTTP/2 or QUIC connection just using connection - level commands . You could make TAPS automatically close a connection if all user streams are closed , but that 's ... not great ? 
 What 's the problem with closing a connection ( I presume you mean the underlying transport 's one , not the one exposed by TAPS ) once all user streams ( i.e. , grouped TAPS Connections ) are closed ? I think this would obviously happen . If I , as a user , want to avoid delay for connection establishment and tear - down , I 'm not closing my Connection ... Else , closing a group containing multiple open Connections in one go would be a matter of issuing " Close " for all of them ... e.g. , by checking the Connection 's group number , in a loop . We could spec that as part of the API , but it does n't seem to be extremely useful to me , as this function could very easily be written on top of the TAPS API . 
 This works for me ,    discussed : make ConnectionGroup an explicit object ( as opposed to just a [ ] Connection ) , and add ( at least ) an AbortGroup call on it . Another option : add AbortGroup to a Connection , which aborts all connections in the group . Discussion at December interim leans toward the second : do n't create a new object for only one operation . 
 Also , make sure to be clear that  ( ) does NOT close all entangled Connections . ( same thing for Close ( ) )
Paragraph (version A):
Close terminates a Connection after satisfying all the requirements
that were specified regarding the delivery of Messages that the
application has already given to the Transport Services system.  For
example, if reliable delivery was requested for a Message handed over
before calling Close, the Closed Event will signify that this Message
has indeed been delivered.  If the Remote Endpoint still has data to
send, it cannot be received after this call.
Paragraph (version B):
Close terminates a Connection after satisfying all the requirements
that were specified regarding the delivery of Messages that the
application has already given to the Transport Services system.  For
example, if reliable delivery was requested for a Message handed over
before calling Close, the Closed Event will signify that this Message
has indeed been delivered.  If the Remote Endpoint still has data to
send, it cannot be received after this call.  This action does not
affect any other Connection that is entangled with this one in a
Connection Group.
Paragraph (version B):
Abort terminates a Connection without delivering any remaining data.
This action does not affect any other Connection that is entangled
with this one in a Connection Group.
Paragraph (version B):
AbortGroup terminates a Connection and also terminates any other
Connections that are entangled with this one in a Connection Group.
For example, all of the Connections in a group might be streams of a
single session for a multistreaming protocol; aborting the entire
group would close the underlying session.  See also groups.
Draft: draft-ietf-taps-impl

Commentary: The implementation draft should explain that a framer can go into a passthrough / inactive mode once it has finished ( like SOCKS , STARTTLS , CONNECT ) .
Paragraph (version A):
Before an implementation marks a Message Framer as ready, it can also
dynamically add a protocol or framer above it in the stack.  This
allows protocols like STARTTLS, that need to add TLS conditionally,
to modify the Protocol Stack based on a handshake result.
Paragraph (version B):
Before an implementation marks a Message Framer as ready, it can also
dynamically add a protocol or framer above it in the stack.  This
allows protocols that need to add TLS conditionally, like STARTTLS
RFC3207, to modify the Protocol Stack based on a handshake result.
Paragraph (version B):
A Message Framer might also choose to go into a passthrough mode once
an initial exchange or handshake has been completed, such as the
STARTTLS case mentioned above.  This can also be useful for proxy
protocols like SOCKS RFC1928 or HTTP CONNECT RFC7230.  In such cases,
a Message Framer implementation can intercept sending and receiving
of messages at first, but then indicate that no more processing is
needed.