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

Commentary: Review the use of and markdown in the API document , and make it consistent . 
 A fantastic PR ! The best ever !
Paragraph (version A):
Array: Denoted []Type, an instance takes a value for each of zero
or more elements in a sequence of the given Type.  An array may be
of fixed or variable length.
Paragraph (version B):
Array: Denoted "[]Type", an instance takes a value for each of
zero or more elements in a sequence of the given Type.  An array
may be of fixed or variable length.
Paragraph (version A):
Setting this property to "Active", can have privacy implications: It
enables the transport to establish connectivity using alternate paths
that might result in users being linkable across the multiple paths,
even if the "advertisesAltaddr" property (see altaddr below) is set
to false.
Paragraph (version B):
Setting this property to "Active" can have privacy implications: It
enables the transport to establish connectivity using alternate paths
that might result in users being linkable across the multiple paths,
even if the "advertisesAltaddr" property (see altaddr below) is set
to false.
Draft: draft-ietf-taps-arch

Commentary: Clarified one use of word " API " comes just after discussion of the socket API . Tried to fix specialised features to say they define additional requirements . Minor changes to wording , with no intended changes to substance . 
 LGTM but I made one very small comment
Paragraph (version A):
Separate from events, callbacks are also provided for asynchronous
interactions with the Transport Services API, which are not directly
related to events on the network or network interfaces.
Paragraph (version B):
Separate from events, callbacks are also provided for asynchronous
interactions with the Transport Services API that are not directly
related to events on the network or network interfaces.
Draft: draft-ietf-taps-interface

Commentary: " In effect , each leaf node will send the same early application data , yet encoded ( encrypted ) differently on the wire . " : There has been a warning on the privacy implications of using the same token on different paths ; does n't sending an identical 0 - RTT message racingly on multiple transports cause similar correlation issues ? 
 This may be better to put in the privacy and security considerations section of the API document , particularly that doing cleartext 0 - RTT data that races can be recognized on the path ( as opposed to being in TLS which fixes this ) . 
 Similarly , connection racing overall can let a server observe that a client has multiple addresses and what they are , etc . 
 LGTM ; note that I left a tiny comment .
Paragraph (version A):
Applications should be aware that communication attempts can lead to
more than one connection establishment.  This is the case, for
example, when the Transport Services system also executes name
resolution, when support mechanisms such as TURN or ICE are used to
establish connectivity, if protocols or paths are raised, or if a
path fails and fallback or re-establishment is supported in the
Transport Services system.
Paragraph (version B):
Applications should be aware that communication attempts can lead to
more than one connection establishment.  This is the case, for
example, when the Transport Services system also executes name
resolution, when support mechanisms such as TURN or ICE are used to
establish connectivity, if protocols or paths are raised, or if a
path fails and fallback or re-establishment is supported in the
Transport Services system.  Applications should take special care
when using 0-RTT session resumption (see prop-0rtt), as early data
sent across multiple paths during connection establishment may reveal
information that can be used to correlate endpoints on these paths.
Draft: draft-ietf-taps-impl

Commentary: ( More out of curiosity , with no expectation that this would find its way into the text unless you think I 've hit a bug ): In UDP Multicast Receive , which kind of ICMP notifications can come in there that would constitute a ConnectionError -- given that this transport does not send ( and would thus usually not trigger any ) ? 
 Section 10.4 for multicast receive mentions ICMP errors . You could have errors on initiate for joining a multicast group , etc , but it likely does n't make sense to have ICMP errors mentioned here . 
 Suggest we can close this issue . 
 LGTMSeems like we do not loose anything by removing this . The change WFM .
Paragraph (version B):
Calling "AbortGroup" on a UDP Connection (ABORT.UDP(-Lite)) is
identical to calling "Close" on this Connection and on all
Connections in the same ConnectionGroup.
Paragraph (version A):
UDP Multicast Receive Connections generate an InitiateError if
Initiate is called.
Paragraph (version A):
Once in use, UDP throws "soft errors" (ERROR.UDP(-Lite)) upon
receiving ICMP notifications indicating failures in the network.
Paragraph (version B):
UDP Multicast Receive Connections generate an InitiateError
indicating that joining a multicast group failed if Initiate is
called.
Draft: draft-ietf-taps-impl

Commentary: Framers : The < ttparagraphs in Defining Message Framers and later might be formal language or pseudocode , I ca n't tell . It might help if the introduction stated something around names and signatures of signals and functions being expressed in pseudocode , and that identifiers in implementations are expected to be similar to those but following the conventions of the language 
 We should reference section 1.1 of the API document which defines the notation used .
Paragraph (version B):
The API examples in this section use the notation conventions for the
Transport Services API defined in Section 1.1 of I-D.ietf-taps-
interface.
Draft: draft-ietf-taps-impl

Commentary: First cut at new text 
 UDP , ConnectionError : Would those soft errors contain additional information about the ICMP error code , and can an application expect to find the ( partial ) original datagram in the error ? 
 This is a good question ! - on the one hand , the additional info can be valuable - for example to validate an ICMP message , as suggested for validating ICMP for a DPLPMTUD probe - but on the other hand , this info is often not provided by existing APIs . 
 I figure that a practical thing to state would be that the information is provided if it is accessible on a platform . Having text that describes this as matter of implementation quality would help TAPS implementers push for ( eg . MSG_ERRQUEUE style ) provisions in their platforms . 
 If the system makes this information available , we could mention that you could pass it up . 
 See a proposal in 
 The pointer to the PR with the specific proposal to address this issue got a " thumbs up " from the who wrote the review . So , this PR should have closed this issue . Doing it manually .
Paragraph (version A):
Once in use, UDP throws "soft errors" (ERROR.UDP(-Lite)) upon
receiving ICMP notifications indicating failures in the network.
Paragraph (version B):
Once in use, UDP throws "soft errors" (ERROR.UDP(-Lite)) upon
receiving ICMP notifications indicating failures in the network.
Additional information can also be provided when this is available
to the system (e.g.  ICMP error code and quoted packet header).
Draft: draft-ietf-taps-impl

Commentary: Appendix B.1 lists two properties as " under discussion " : on Send or Receive Rate : ( PR 1036 fixes the name ): this is no longer under discussion , these properties exist . Preferences : this is no longer under discussion , I suppose ? ? We do n't have this in the interface draft . So I have the impression that this should no longer be an appendix , the text on Cost Preferences should be removed , and the text on Bounds on Send and Receive Rate should be moved elsewhere , and not be mentioned as " under discussion " . 
 LGMT
Paragraph (version B):
As another example, branch sorting can also be influenced by bounds
on the Send or Receive rate (Selection Properties "minSendRate" /
"minRecvRate" / "maxSendRate" / "maxRecvRate"): if the application
indicates a bound on the expected Send or Receive bitrate, an
implementation may prefer a path that can likely provide the desired
bandwidth, based on cached maximum throughput, see performance-
caches.  The application may know the Send or Receive Bitrate from
metadata in adaptive HTTP streaming, such as MPEG-DASH.
Draft: draft-ietf-taps-impl

Commentary: Two items here :   ? I guess this is just a guidance document so does n't need anything normative . There 's some later " should " as well which I would generally ask the same question for . but ... here we have some NORMATIVE language . That SHOULD should probably be non - capitalised to align with earlier usage . ( and so on later in the document , e.g. in the SCTP description ) 
 The first one can just be " uses the default values " , without normative text . Second one can be lowercase as well . SCTP has normative SHOULDs and MUSTs that can be removed .
Paragraph (version A):
The implementation stores these properties as a part of the
Preconnection object for use during connection establishment.  For
Selection Properties that are not provided by the application, the
implementation must use the default values specified in the Transport
Services API (I-D.ietf-taps-interface).
Paragraph (version B):
The implementation stores these properties as a part of the
Preconnection object for use during connection establishment.  For
Selection Properties that are not provided by the application, the
implementation uses the default values specified in the Transport
Services API (I-D.ietf-taps-interface).
Draft: draft-ietf-taps-interface

Commentary: This seems otherwise inconsistent : for the noFragmentation property , we say that , in case of IPv4 , setting this will result in setting the " Do n't Fragment " bit . the noSegmentation property is described as avoiding fragmentation AND avoiding segmentation . So logically , this should also result in setting the " Do n't Fragment " bit in case of IPv4 . Generally , I 'm not sure how an implementer should interpret the " can " here , in contrast with the " will " in the " Do n't Fragment " case above ... the textual difference seems to hint that this could be implemented differently , but then , how ?
Paragraph (version A):
This only takes effect when the transport uses a network layer that
supports this functionality.  When it does take effect, setting this
property to true will cause the sender to avoid network-layer source
frgementation.  When using IPv4, this will result in the Don't
Fragment bit being set in the IP header.
Paragraph (version B):
This only takes effect when the transport uses a network layer that
supports this functionality.  When it does take effect, setting this
property to true will cause the sender to avoid network-layer source
fragmentation.  When using IPv4, this will result in the Don't
Fragment bit being set in the IP header.
Paragraph (version A):
When set to true, this property requests the transport layer to not
provide segmentation of messages larger than the maximum size
permitted by the network layer, and also to avoid network-layer
source fragmentation of messages.  When running over IPv4, setting
this property to true can result in a sending endpount setting the
Don't Fragment bit in the IPv4 header of packets generated by the
transport layer.  An attempt to send a message that results in a size
greater than the transport's current estimate of its maximum packet
size (singularTransmissionMsgMaxLen) will result in a SendError.
This only takes effect when the transport and network layer support
this functionality.
Paragraph (version B):
When set to true, this property requests the transport layer to not
provide segmentation of messages larger than the maximum size
permitted by the network layer, and also to avoid network-layer
source fragmentation of messages.  When running over IPv4, setting
this property to true will result in a sending endpount setting the
Don't Fragment bit in the IPv4 header of packets generated by the
transport layer.
Paragraph (version B):
An attempt to send a message that results in a size greater than the
transport's current estimate of its maximum packet size
("singularTransmissionMsgMaxLen") will result in a "SendError".  This
only takes effect when the transport and network layer support this
functionality.
Draft: draft-ietf-taps-impl

Commentary: SORRY I made a PR on your PR , when I meant to leave a review comment , see 1024 . .... Silly to make a PR on a PR - I a review comment instead ... 
 In section 4.1.4 in the impl draft , we have : " The order of operations for branching , where lower numbers are acted upon first , should be : Paths Options Endpoints " However , I would say there is not really a strict ordering required . The text actually indicates that selection of the protocol is rather independent while there is usually a dependency between the interface and derived endpoint . I think this is related to my other issue about the use of the term path , because a path consists of both the local and remote endpoint and therefore there is of course a dependency . So in summary I 'm not sure how useful I find this whole section as currently written ... 
 We should conclude if anything more is needed here besides cleaning up the terminology , where Alternate Paths is not a good term - see . 
 Any implementation should have a consistent order of operations . This is a recommended example . Reference the arch text that says it needs to work the same way each time . 
 Reference ICE / HE
Paragraph (version A):
Branch types must occur in a specific order relative to one another
to avoid creating leaf nodes with invalid or incompatible settings.
In the example above, it would be invalid to branch for derived
endpoints (the DNS results for www.example.com) before branching
between interface paths, since there are situations when the results
will be different across networks due to private names or different
supported IP versions.  Implementations must be careful to branch in
an order that results in usable leaf nodes whenever there are
multiple branch types that could be used from a single node.
Paragraph (version B):
Branch types ought to occur in a specific order relative to one
another to avoid creating leaf nodes with invalid or incompatible
settings.  In the example above, it would be invalid to branch for
derived endpoints (the DNS results for www.example.com) before
branching between interface paths, since there are situations when
the results will be different across networks due to private names or
different supported IP versions.  Implementations need to be careful
to branch in a consistent order that results in usable leaf nodes
whenever there are multiple branch types that could be used from a
single node.
Draft: draft-ietf-taps-interface

Commentary: Does this make sense outside of a protocol - specific context ? I am aware that this is a different can of worms adding protocol specific parameters to clone , but this looks like a strange concept to add an Integer here that may have different side effects in QUIC and SCTP … 
 That 's a very good question . This feature request came up in the QuIC mapping part of the discussion in Vienna , see : Not sure what to do : keep it as it is , remove it , or add the protocol : assign : " if protocol = x , then stream ID = y " read : " stream ID is y , and your protocol is x " I have to say , I do n't like this particular way , as it would complicate matters quite a bit . But how else to do it ? 
 All of the multistreaming protocols we know about have an integer stream identifier . I suppose a future protocol could use some sort of binary blob for identifying streams ( which are ... pedantically ... representable as arbitrary - length integers ) 
 Interim discussion : let 's make Clone ( ) and Initiate ( ) take a group of protocol - specific parameters ( optionally ) which allow protocols like QUIC and SCTP to extend this . 
 I just made a very minimalist update , where " protocolSpecificProperties " is only a parameter of Clone ( ) . Why not list it as readable properties , and why not as a parameter of Initiate , as we discussed ? What 's the point of saying " there can be protocol - specific properties which are currently not defined , and they can be readable " ? This is for a future spec to say , when it proposes a new transport property . Regarding Initiate ( ) , I think this should in fact not be a parameter to the Initiate Action itself , but a transport property to be supplied when creating a Preconnection . Again , this made me find that I would only write something like " There can also be transport properties that are not yet defined " , which does n't seem to be useful text . In conclusion , I found that only the Clone ( ) Action needs this as a new parameter . Everything else is for future mapping documents . Thoughts ? 
 Many thanks ! I incorporated your suggestion , and made a tiny edit to it ( behaviour = behavior , underlaying = underlying , and " stream or connection " instead of " stream / connection " ) . 
 ... combined with " if the transport is mux'ing , else ... " 
 Thanks – I guess we have a fairly good solution .
Paragraph (version B):
The optional "connectionProperties" parameter allows passing
Transport Properties that control the behavior of the underlying
stream or connection to be created, e.g., protocol-specific
properties to request specific stream IDs for SCTP or QUIC.
Draft: draft-ietf-taps-impl

Commentary: Raising this issue as part of my review of the the Implementation Draft . Quoting from Section 4.1 " Structuring Candidates as a Tree " ~ Feedback : While it is understood that " connection attempt " is here used to refer to a given node in the tree , rather than the actual ( stateful ) process of attempting to connect to the given endpoint ( using the given parameters ) , it does not make for easy reading . Similarly , it is possible to grasp how an " aggregate set " can be " viewed " as " a single connection establishment " , but the language could be clearer here as well . Could n't an " attempt " that has succeeded and is " ready to use " be referred to differently ? Could n't " candidate " or " option " be substituted for " attempt " to improve readability ? Proposal : 
 Seems quite close to me 
 Yes , I like this proposed text .
Paragraph (version A):
When an implementation views this aggregate set of connection
attempts as a single connection establishment, it only will use one
of the leaf nodes to transfer data.  Thus, when a single leaf node
becomes ready to use, then the entire connection attempt is ready to
use by the application.  Another way to represent this is that every
leaf node updates the state of its parent node when it becomes ready,
until the trunk node of the tree is ready, which then notifies the
application that the connection as a whole is ready to use.
Paragraph (version B):
When an implementation is asked to establish a single connection,
only one of the leaf nodes in the candidate set is needed to transfer
data.  Thus, once a single leaf node becomes ready to use, then the
connection establishment tree is considered ready.  One way to
implement this is by having every leaf node update the state of its
parent node when it becomes ready, until the trunk node of the tree
is ready, which then notifies the application that the connection as
a whole is ready to use.
Draft: draft-ietf-taps-arch

Commentary: This pull requests fixes two minor typos in draft - ietf - taps- that I noticed during detailed reading of the draft .
Paragraph (version A):
System-implementation concepts, which are intended to be
internally used by aTransport Services implementation.
Paragraph (version B):
System-implementation concepts, which are intended to be
internally used by a Transport Services implementation.
Draft: draft-ietf-taps-interface

Commentary: in architecture . 
 Per slide 14 in    presentation at IETF 113 : , clarify that the API is defined in terms of events to be general , not because you have to implement an event system if you 're going to implement TAPS . 
 LGTM
Paragraph (version A):
Events are sent to the application or application-supplied code (e.g.
framers, see framing) for processing; the details of event processing
are platform- and implementation-specific.
Paragraph (version B):
Events are sent to the application or application-supplied code (e.g.
framers, see framing) for processing; the details of event interfaces
are platform- and implementation-specific, and may be implemented
using other forms of asynchronous processing, as idiomatic for the
implementing platform.
Paragraph (version A):
Originally, the Socket API presented a blocking interface for
establishing connections and transferring data.  However, most modern
applications interact with the network asynchronously.  Emulation of
an asynchronous interface using the Socket API generally uses a try-
and-fail model.  If the application wants to read, but data has not
yet been received from the peer, the call to read will fail.  The
application then waits and can try again later.  In contrast to the
Socket API, all interaction using the Transport Services API is
expected to be asynchronous and use an event-driven model (see
events).  For example, an application first issues a call to receive
new data from the connection.  When delivered data becomes available,
this data is delivered to the application using asynchronous events
that contain the data.  Error handling is also asynchronous; a
failure to send data results in an asynchronous error event.
Paragraph (version B):
Originally, the Socket API presented a blocking interface for
establishing connections and transferring data.  However, most modern
applications interact with the network asynchronously.  Emulation of
an asynchronous interface using the Socket API generally uses a try-
and-fail model.  If the application wants to read, but data has not
yet been received from the peer, the call to read will fail.  The
application then waits and can try again later.
Paragraph (version B):
In contrast to the Socket API, all interaction using the Transport
Services API is expected to be asynchronous.  The API is defined
around an event-driven model (see events) in order to model this
asynchronous interaction, though other forms of asynchronous
communication may be available to applications depending on the
platform implementing the interface.
Paragraph (version B):
For example, an application first issues a call to receive new data
from the connection.  When delivered data becomes available, this
data is delivered to the application using asynchronous events that
contain the data.  Error handling is also asynchronous; a failure to
send data results in an asynchronous error event.