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

Commentary: This adds SO_reuse commentry on the multicast UDP service . It seeks to 
 The implementation document should explain  joining and SO_REUSEADDR for multicast 
 Text blob for thought or incorporation : In some uses , it is required to open multiple connections for the same address(es ) . This is used for some multicast applications . For example , one connection might be opened to listen to a multicast group , and later a separate one to send to the same group ; two applications might independently listen to the same address(es ) to send signals to and/or receive signals from a common multicast control bus . In these cases , the interface needs to explicitly enable re - use of the same set of addresses ( equivalent to setting SO_REUSEADDR in the socket API ) .
Paragraph (version B):
There are cases where it is required to open multiple connections for
the same address(es).  For example, one Connection might be opened
for a multicast group to for a multicast control bus, and another
application later opens a separate Connection to the same group to
send signals to and/or receive signals from the common bus.  In such
cases, the interface needs to explicitly enable re-use of the same
set of addresses (equivalent to setting SO_REUSEADDR in the socket
API).
Draft: draft-ietf-taps-interface

Commentary: The text below is a bit confusing as there are no details about how to to send replies and map responses to their requests in Section 7.1.1 . This can be easily fixed by clarifying what Section 7.1.1 provides details on . But I was also wondering if there should be some more details on how to send replies and map responses to their requests somewhere ? 
 Note : this will be in § 9.3.2.1 . after merge . 
 Is seems the concept of mapping requests / replies has been fully eliminated . So just removing this part of the example . 
 Thanks  , LGTM .
Paragraph (version A):
The messageData object provides access to the bytes that were
received for this Message, along with the length of the byte array.
The messageContext is provided to enable retrieving metadata about
the message and referring to the message, e.g., to send replies and
map responses to their requests.  See msg-ctx for details.
Paragraph (version B):
The messageData object provides access to the bytes that were
received for this Message, along with the length of the byte array.
The messageContext is provided to enable retrieving metadata about
the message and referring to the message.  The messageContext object
ist described in msg-ctx.
Draft: draft-ietf-taps-interface

Commentary: Interface , Section 2 , " A unified interface to datagram and connection - oriented transports , allowing use of a common API for connection - establishment and closing " . Should this be " … to datagram and stream - oriented transports " ? At what point do we explain that and are also used for connectionless protocols ? This change would finesse the question here , leaving it for Section 3 , or we can restructure the draft to clarify earlier . 
 Yes to ( 1 ): Datagram protocols can be connection - oriented or not ; however the point here seems to be either : /interface to datagram and stream - oriented transports/ or /interface to both connection - less and connection - oriented transports/ ... I 'd favour the first , it 's clear enough and does n't use terms that we later re - use . Also to ( 2 ): I think we could insert a specific sentence after : " A Connection represents an instance of a transport   on which data can be sent to and/or received from a Remote Endpoint ( i.e. , depending on the kind of transport , connections can be bi - directional or unidirectional ) . " That explicitly says something like : " This connections are presently consistently to the application , irrespective of whether the underlying transport is connection - less and connection - oriented . "
Paragraph (version A):
A unified interface to datagram and connection-oriented
transports, allowing use of a common API for connection-
establishment and closing.
Paragraph (version B):
A unified interface to datagram and stream-oriented transports,
allowing use of a common API for connection establishment and
closing.
Paragraph (version A):
An application primarily interacts with this API through two Objects:
Preconnections and Connections.  A Preconnection object (pre-
establishment) represents a set of properties and constraints on the
selection and configuration of paths and protocols to establish a
Connection with an Endpoint.  A Connection object represents an
instance of a transport Protocol Stack on which data can be sent to
and/or received from a Remote Endpoint (i.e., a logical connection
that, depending on the kind of transport, can be bi-directional or
unidirectional, and that can use a stream protocol or a datagram
protocol).  Connections can be created from Preconnections in three
ways: by initiating the Preconnection (i.e., actively opening, as in
a client; initiate), through listening on the Preconnection (i.e.,
passively opening, as in a server listen), or rendezvousing on the
Preconnection (i.e., peer to peer establishment; rendezvous).
Paragraph (version B):
by initiating the Preconnection (i.e., actively opening, as in a
client; initiate),
Paragraph (version B):
through listening on the Preconnection (i.e., passively opening,
as in a server listen),
Paragraph (version B):
or rendezvousing on the Preconnection (i.e., peer to peer
establishment; rendezvous).
Draft: draft-ietf-taps-interface

Commentary: In response to ... This moves the discussion of protocol instances into bullet 4 , and the properties ( mainly selection ) into bullet 5 . It does not intend to change any text , and is intended to avoid what appeared to be overlap . 
 Resolved issue following MW review 
 I do not understand the relationship between bullets four and five . They seem to overlap ? 
 :  , is this resolved by this PR : Re - group managing properties & protocol instances ? 
 LGTM , but note that I marked a nit ( missing full stop ) .
Paragraph (version A):
For Connections that are Established or Closing: Transport
Properties that the application specified on the Preconnection.
Selection Properties indicate whether or not the Connection has or
offers a certain Selection Property, see selection-props
The actually instantiated protocol stack might not match all
Protocol Selection Properties that the application specified on
the Preconnection.  For example, a certain Protocol Selection
Property that an application specified as Preferred might not
actually be present in the chosen protocol stack because none of
the currently available transport protocols had this feature.
Selection properties of type "Preference" will be exposed as
boolean values indicating whether or not the property applies to
the selected transport.
Paragraph (version B):
For Connections that are Established or Closing: Transport
Properties that the application specified on the Preconnection.
Selection Properties indicate whether or not the Connection has or
offers a certain Selection Property, see selection-props.
The actually instantiated protocol stack might not match all
Protocol Selection Properties that the application specified on
the Preconnection.  For example, a certain Protocol Selection
Property that an application specified as Preferred might not
actually be present in the chosen protocol stack because none of
the currently available transport protocols had this feature.
Selection properties of type "Preference" will be exposed as
boolean values indicating whether or not the property applies to
the selected transport.
Draft: draft-ietf-taps-arch

Commentary: Added a couple of sentences to  that are hoped to early introduce that connections are things in the API , not aretfacts of the transport protocol instances . Different to , but related to an issue for the description in API . 
 " A is an abstraction that represents the communication . If the transport services interface selects a protocol such as TCP for the communication , a will correspond to an underlying protocol connection . In the other hand , if a protocol such as UDP is selected , the remains an abstraction in the end points and does n't correspond to explicit protocol state " ? 
 : Could you live with the update in this PR ? 
 yes , I think so ( assuming I 'm reading the diff right )
Paragraph (version A):
concepts presents the Transport Services architecture diagram and
defines the concepts that are used by both the API and
implementation documents.  The Preconnection allows applications
to configure Connection Properties, and the Connection represents
an object that can be used to send and receive Messages.  A
connection is a local operation that serves to simplify the local
send/receive functions and to filter the traffic for the endpoint.
This might (as in TCP) or might not (as in UDP) represent an end-
to-end protocol connection across the network path.
Paragraph (version B):
concepts presents the Transport Services architecture diagram and
defines the concepts that are used by both the API and
implementation documents.  The Preconnection allows applications
to configure Connection Properties, and the Connection represents
an object that can be used to send and receive Messages.
Paragraph (version B):
A Connection is an abstraction that represents the communication.
If the transport services interface selects a protocol such as TCP
for the communication, a Connection will correspond to an
underlying protocol connection.  If however a protocol such as UDP
is selected, the Connection remains an abstraction at the end
points.
Draft: draft-ietf-taps-impl

Commentary: This is a first cut , I 'll update next . 
 The Capacity Profile in the API draft ( now ) lists these possible choices : Default , Scavenger , Low Latency / Interactive , Low Latency / Non - Interactive , Constant - Rate Streaming and Capacity - Seeking . The text in section 4.1.3 only discusses Scavenger , Low Latency / Interactive , and Constant - Rate Streaming . 
 Aha - I could offer to align the Capacity Profile classes ? 
 See a PR to align Capacity profile with API 
 Resolved 
 LGTM , thanks !
Paragraph (version A):
Capacity-Seeking: Prefer adpating to paths to determine the
highest available capacity, based on the observed maximum
throughput.
Paragraph (version B):
Capacity-Seeking: Prefer adapting to paths to determine the
highest available capacity, based on the observed maximum
throughput.
Draft: draft-ietf-taps-interface

Commentary: I know we have discussed Multipath Transport many times , but when reading is seems strange when you get to Multipath Transport and here there is no option to " Require " this property , only to " Prefer " it . We should at least say why . It is perhaps intuitive that you do not need to distinguish between Avoid and Prohibit , but not why  would not be useful . 
 Add a sentence after this to explain why " require " would n't make sense : 
 This reflects what we agreed on , during the last interim .
Paragraph (version A):
Enumeration values other than "Disabled" are interpreted as a
preference for choosing protocols that can make use of multiple
paths.  The "Disabled" value implies a requirement not to use
multiple paths in parallel but does not prevent choosing a protocol
that is capable of using multiple paths, e.g., it does not prevent
choosing TCP, but prevents sending the "MP_CAPABLE" option in the TCP
handshake.
Paragraph (version B):
Note that Multipath Transport has no corresponding Selection Property
of type Preference.  Enumeration values other than "Disabled" are
interpreted as a preference for choosing protocols that can make use
of multiple paths.  The "Disabled" value implies a requirement not to
use multiple paths in parallel but does not prevent choosing a
protocol that is capable of using multiple paths, e.g., it does not
prevent choosing TCP, but prevents sending the "MP_CAPABLE" option in
the TCP handshake.
Draft: draft-ietf-taps-interface

Commentary: Fix a bunch of nits 
 Looks good . 
 I would just go ahead and merge it , but , sigh , it has a conflict ... I hope someone more git - savvy than me can solve this . 
 Looks good
Paragraph (version A):
Applications that adopt this interface will benefit from a wide set
of transport features that can evolve over time.  This protocol-
independent API ensures that the system providing the interface can
optimize its behavior based on the application requirements and
network conditions, without requiring changes to the applications.
This flexibility enables faster deployment of new features and
protocols.  It can support applications by offering racing and
fallback mechanisms, which otherwise need to be separately
implemented in each application.
Paragraph (version B):
Applications that adopt this interface will benefit from a wide set
of transport features that can evolve over time.  This protocol-
independent API ensures that the system providing the interface can
optimize its behavior based on the application requirements and
network conditions, without requiring changes to the applications.
This flexibility enables faster deployment of new features and
protocols, and can support applications by offering racing and
fallback mechanisms, which otherwise need to be separately
implemented in each application.
Paragraph (version A):
Preconnection (i.e.  peer to peer establishment; rendezvous).
Paragraph (version B):
Preconnection (i.e., peer to peer establishment; rendezvous).
Paragraph (version A):
Rendezvous is to occur based on the Preconnection.
Paragraph (version B):
Rendezvous() is to occur based on the Preconnection.
Draft: draft-ietf-taps-impl

Commentary: Nit : Section 3.1 : No such protocol … 
 I ’ll argue this “ but no such protocol is available on the host running the transport system ” is asking for a feature , so I think the text ought to read : “ but no such feature is available in any protocol the host running the transport system ” 
 " but no protocol available on the host offers such a feature " 
 This was fixed in the already merged PR .
Paragraph (version A):
A request by an application for Protocol Properties that include
requirements or prohibitions that cannot be satisfied by any of
the available protocols.  For example, if an application requires
"Configure Reliability per Message", but no such protocol is
available on the host running the transport system this should
result in an error, e.g., when SCTP is not supported by the
operating system.
Paragraph (version B):
A request by an application for Protocol Properties that include
requirements or prohibitions that cannot be satisfied by any of
the available protocols.  For example, if an application requires
"Configure Reliability per Message", but no such feature is
available in any protocol the host running the transport system on
the host running the transport system this should result in an
error, e.g., when SCTP is not supported by the operating system.
Draft: draft-ietf-taps-impl

Commentary: Trying to address use of “ remote ” and " local " 
 The use of “ remote ” on its own offends me : “ Some types of remote might … ” could we make this “ Remote Endpoint ” to ease my reading ? or whatever else is intended ? Similarly can we change “ locals ” and “ remote ” here to something that is defined : “ This can expose some or all of the candidate locals to the remote ” 
 Remote Endpoint
Paragraph (version A):
The process of connection establishment completes when one leaf node
of the tree has successfully completed negotiation with the Remote
Endpoint , or else all nodes of the tree have failed to connect.  The
first leaf node to complete its connection is then used by the
application to send and receive data.
Paragraph (version B):
The process of connection establishment completes when one leaf node
of the tree has successfully completed negotiation with the Remote
Endpoint, or else all nodes of the tree have failed to connect.  The
first leaf node to complete its connection is then used by the
application to send and receive data.
Draft: draft-ietf-taps-interface

Commentary: The use of “ remote ” on its own offends me : “ Some types of remote might … ” could we make this “ Remote Endpoint ” to ease my reading ? or whatever else is intended ? Similarly can we change “ locals ” and “ remote ” here to something that is defined : “ This can expose some or all of the candidate locals to the remote ” 
 Remote Endpoint
Paragraph (version A):
An application primarily interacts with this API through two Objects:
Preconnections and Connections.  A Preconnection represents a set of
properties and constraints on the selection and configuration of
paths and protocols to establish a Connection with a Endpoint.  A
Connection represents an instance of a transport Protocol Stack on
which data can be sent to and/or received from a Remote Endpoint
(i.e., depending on the kind of transport, connections can be bi-
directional or unidirectional).  Connections can be created from
Preconnections in three ways: by initiating the Preconnection (i.e.,
actively opening, as in a client), through listening on the
Preconnection (i.e., passively opening, as in a server), or
rendezvousing on the Preconnection (i.e.  peer to peer
establishment).
Paragraph (version B):
An application primarily interacts with this API through two Objects:
Preconnections and Connections.  A Preconnection represents a set of
properties and constraints on the selection and configuration of
paths and protocols to establish a Connection with an Endpoint.  A
Connection represents an instance of a transport Protocol Stack on
which data can be sent to and/or received from a Remote Endpoint
(i.e., depending on the kind of transport, connections can be bi-
directional or unidirectional).  Connections can be created from
Preconnections in three ways: by initiating the Preconnection (i.e.,
actively opening, as in a client), through listening on the
Preconnection (i.e., passively opening, as in a server), or
rendezvousing on the Preconnection (i.e.  peer to peer
establishment).
Draft: draft-ietf-taps-interface

Commentary: This attempts to clarify transport segmentation ( a sparate PR will propose to clarify  ) 
   part of the  story
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.  It exposes the Maximum
Packet Size (MPS) as described in Datagram PLPMTUD RFC8899.
Paragraph (version B):
This property, if applicable, represents the maximum Message size
that can be sent without incurring network-layer fragmentation at the
sender.  It exposes a value to the application based on the Maximum
Packet Size (MPS) as described in Datagram PLPMTUD RFC8899.  This can
allow a sending stack to avoid unwanted fragmentation at the network-
layer or segmentation by the transport layer.
Paragraph (version A):
When set to true, this property requests the network layer at the
sending endpoint to not fragment the packets generated by the
transport layer.  When running over IPv4, setting this property to
true will also cause the Don't Fragment bit to be set in the IP
header.  When this property is set, an attempt to send a message 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 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.
Draft: draft-ietf-taps-interface

Commentary: For other parameters you have to pass in an empty object if you do not want to set anything but not for SecurityParameters . Unclear why the parameters are treated differently ? 
 Make security parameters non - optional Remove " Transport Properties MUST always be specified while security parameters are OPTIONAL . " Define that there is an implementation - specific security parameter to disable security 
 LGTM , thanks !
Paragraph (version A):
Transport Properties MUST always be specified while security
parameters are OPTIONAL.
Paragraph (version B):
Connections that use Transport Services SHOULD use security in
general.  However, for compatibility with endpoints that do not
support transport security protocols (such as a TCP endpoint that
does not support TLS), applications can initialize their security
parameters to indicate that security can be disabled, or can be
opportunistic.  If security is disabled, the Transport Services
system will not attempt to add transport security automatically.  If
security is opportunistic, it will allow Connections without
transport security, but will still attempt to use security if
available.
Draft: draft-ietf-taps-interface

Commentary: Section 4.2 : " In such cases , implementations SHOULD prioritize Selection Properties that select paths over those that select protocols . " I think I agree to this recommendation but it comes a little out of nowhere and we should probably provide some reasoning , especially as this is normative . 
 Proposing to change text to address the application developer : to expect that the path selection properties would be preferred over protocol selection properties . We should also explain a bit of the rationale , to explain that path properties are generally more sensitive around policy / expense .
Paragraph (version A):
Note that application preferences can conflict with each other.  For
example, if an application indicates a preference for a specific path
by specifying an interface, but also a preference for a protocol, a
situation might occur in which the preferred protocol is not
available on the preferred path.  In such cases, implementations
SHOULD prioritize Selection Properties that select paths over those
that select protocols.  Therefore, the transport system SHOULD race
the path first, ignoring the protocol preference if a specific
protocol does not work on the path.
Paragraph (version B):
Note that application preferences can conflict with each other.  For
example, if an application indicates a preference for a specific path
by specifying an interface, but also a preference for a protocol, a
situation might occur in which the preferred protocol is not
available on the preferred path.  In such cases, applications can
expect properties that determine path selection to be prioritized
over properties that determine protocol selection.  The transport
system SHOULD determine the preferred path first, regardless of
protocol preferences.  This ordering is chosen to provide consistency
across implementations, based on the fact that it is more common for
the use of a given network path to determine cost to the user (i.e.,
an interface type preference might be based on a user's preference to
avoid being charged more for a cellular data plan).