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

Commentary: Sections 4.1 and 4.1.3 introduce to configure an Endpoint Object . The address supplied in examples appears to be an address literal . However , Section 1.1 does not define any types explicitly associated with an internet address -- or could work , but I do n't think that 's the intent for these APIs , either . Section 3.2.2 does not extend this . It 's unclear whether this literal is intended to support IPv6 scoped addresses as described in [ RFC4007 ] . While this RFC describes a textual representation ( possibly not in line with the goals of the API ) , [ RFC6874 ] describes how to represent zone indexes in an address literal . If zone indexes are not intended to be supported , this could be clarified by , when " IPv4 and IPv6 address " is mentioned in section 4.1 , also citing [ RFC791 ] and [ RFC4007 ] with the respective address family . If zone indexes are intended to be supported , ambiguity exists around the use of and on a Local Endpoint , where the supplied address has a zone index that does not match the supplied interface . This could be clarified by : Defining type names that represent IPv4 and IPv6 addresses in section 1.1 . Specifying the properties of an address literal supported by that type ( referencing [ RFC791 ] for IPv4 and both [ RFC4007 ] and [ RFC6874 ] for IPv6 ) . Clarifying in section 4.1 that " IPv4 or IPv6 address " are of the respective type described in section 1.1 when used in or . Clarifying the behavior of zone index and interface choices on a Local Endpoint in a new section 4.1.4 . This may tie in to to some extent in that this is unlikely to be discoverable until is called . [ RFC791 ] : [ RFC4007 ] : [ RFC6874 ] : 
 ( note this is in § 6.1/6.1.3 post- ) 
 Mention that the % en0 addition to the IPv6 address is equivalent to explicitly setting WithInterface . Also mention that these are implied to be system types for addresses 
 Looks sane
Paragraph (version B):
Note that an IPv6 address specified with a scope (e.g.
"2001:db8:4920:e29d:a420:7461:7073:0a%en0") is equivalent to
"WithIPv6Address" with an unscoped address and "WithInterface "
together.
Draft: draft-ietf-taps-arch

Commentary: Arch : At 4.1.7 , be clearer than " without cleaning up state " .
Paragraph (version A):
Abort: The action the application takes on a Connection to
indicate a Close and also indicate that the Transport Services
system should not attempt to deliver any outstanding data.  This
is intended for immediate termination of a connection, without
cleaning up state.
Paragraph (version B):
Abort: The action the application takes on a Connection to
indicate a Close and also indicate that the Transport Services
system should not attempt to deliver any outstanding data, and
immediately drop the connection.  This is intended for immediate,
usually abnormal, termination of a connection.
Draft: draft-ietf-taps-arch

Commentary: In ( Arch ) section 3.3 , you are talking about racing before you 've described what it is . At the point where you note that racing should only happen over stacks with identical security properties , note when doing so might introduce privacy issues and what can be done about them . 
 Describe what you mean by caching and why you might want to isolate sessions earlier .
Paragraph (version A):
Sockets, for protocols like TCP, are generally limited to connecting
to a single address over a single interface.  They also present a
single stream to the application.  Software layers built upon sockets
often propagate this limitation of a single-address single-stream
model.  The Transport Services architecture is designed to handle
multiple candidate endpoints, protocols, and paths; and support
multipath and multistreaming protocols.
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.  Transport services implementations can
further implement fallback mechanisms if connection establishment of
one protocol fails or performance is detected to be unsatisfactory.
Paragraph (version B):
to provide state caching and application control over it.
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 by racing them and
measuring the results (see 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.
Paragraph (version B):
Information used in connection establishment (e.g. cryptographic
resumption tokens, information about usability of certain protocols
on the path, results of racing in previous connections) are cached in
the transport services implementation.  Applications have control
over whether this information is used for a specific establishment,
in order to allow tradeoffs between efficiency and linkability.
Paragraph (version B):
Whether information from previous racing attempts, or other
information cached by the Transport Services implementation about
past communications, is used during establishment is under
application control.  This allows applications to make tradeoffs
between efficiency (through racing) and privacy (via information that
might leak from the cache toward an on-path observer).  Some
applications have native concepts (e.g. "incognito mode") that align
with this functionality.
Draft: draft-ietf-taps-interface

Commentary: Explain the different use - cases on specifying interfaces to 
 There 's something obvious I 'm not seeing : if I want to specify a multicast or link - local address for an endpoint , why not simply specify that address ? What 's the use of adding the interface into it ? Some addresses will inherently limit interfaces ; I thought interface preference was about preferring wifi to 4 G , etc . 
 Like , in section 6.1.1 : 
 Multicast groups can be scoped ( see RFC7346 ) , thus , may only be available on certain interfaces or even have different meanings based on the interface . So for Interface- and Link - Local scope , specifying the interface is strictly required . For others use cases ( like coping with non - unique use of RFC1918 addresses ) this may also be helpful . 
 Why does the API have both the ability to say LocalSpecifier .  and to set interface requirements on TransportProperties ? Why not just keep the latter and remove the former ? 
 There 's history here : LocalSpecifier . WithInterface predates explicitly setting the interface name in interface requirements . There might be reasons to keep this : LocalSpecifier is more likely to show up in application UI than in transport properties . Any text proposed to keep both would need to have an unambiguous way to resolve conflicts between the two . This might be a source of hard - to - debug errors . 
 To discuss next interim
Paragraph (version B):
Specifying an interface on a RemoteEndpoint qualifies the scope of
the remote endpoint, e.g., for link-local addresses.
Paragraph (version B):
Specifying an interface on a LocalEndpoint explicitly binds all
candidates derived from this endpoint to use the specified
interface.
Paragraph (version B):
Specifying an interface using the "interface" Selection Property
(prop-interface) or indirectly via the "pvd" Selection Property
(prop-pvd) influences the selection among the available
candidates.
Paragraph (version B):
While specifying an interface on an endpoint restricts the candidates
available for connection establishment in the Pre-Establishment
Phase, the Selection Properties prioritize and constrain the
connection establishment.
Paragraph (version B):
Note that this property is not used to specify an interface scope for
a particular endpoint. ifspec provides details about how to qualify
endpoint candidates on a per-interface basis.
Draft: draft-ietf-taps-arch

Commentary: Quote from the API draft : " The present API covers all elements of this section except Notification of Excessive Retransmissions ( early warning below abortion threshold ) . " So ... should n't this MUST be a SHOULD ? 
  will merge this after finishing the PR that updates -interface minset appendix .
Paragraph (version A):
Any functionality that is common across multiple transport protocols
SHOULD be made accessible through a unified set of Transport Services
API calls.  As a baseline, any Transport Services API MUST allow
access to the minimal set of features offered by transport protocols
RFC8923.
Paragraph (version B):
Any functionality that is common across multiple transport protocols
SHOULD be made accessible through a unified set of Transport Services
API calls.  As a baseline, any Transport Services API SHOULD allow
access to the minimal set of features offered by transport protocols
RFC8923.
Draft: draft-ietf-taps-arch

Commentary: Trying to with a hint upfront that connections can be UDP , TCP or any other transport protocol instance ... and then later explain about a connection that can remain an abstraction at the end points for a UDP example . 
 The last bullet in the Overview is out of place - the others are an overview of the document , but this one is a description of a concept .
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.
Paragraph (version A):
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.
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.
Paragraph (version B):
concepts also presents how an abstract Connection is used to
select a transport protocol instance such as TCP, UDP, or another
transport.  The Connection represents an object that can be used
to send and receive Messages.
Paragraph (version A):
Connection: A Connection object represents one or more active
transport protocol instances that can send and/or receive Messages
between local and remote systems.  It holds state pertaining to
the underlying transport protocol instances and any ongoing data
transfers.  This represents, for example, an active Connection in
a connection-oriented protocol such as TCP, or a fully-specified
5-tuple for a connectionless protocol such as UDP.  It can also
represent a pool of transport protocol instances, e.g., a set of
TCP and QUIC connections to equivalent endpoints, or a stream of a
multi-streaming transport protocol instance.  Connections can be
created from a Preconnection or by a Listener.
Paragraph (version B):
Connection: A Connection object represents one or more active
transport protocol instances that can send and/or receive Messages
between local and remote systems.  It is an abstraction that
represents the communication.  The Connection object holds state
pertaining to the underlying transport protocol instances and any
ongoing data transfers.  For example, an active Connection can
represent a connection-oriented protocol such as TCP, or can
represent a fully-specified 5-tuple for a connectionless protocol
such as UDP, where the Connection remains an abstraction at the
end points.  It can also represent a pool of transport protocol
instances, e.g., a set of TCP and QUIC connections to equivalent
endpoints, or a stream of a multi-streaming transport protocol
instance.  Connections can be created from a Preconnection or by a
Listener.
Draft: draft-ietf-taps-arch

Commentary: Be clear that the API is asynchronous ( not the whole arch ) ; and reword the read example to also be asynchronous . 
 In section 2.1 " its call to read will not complete immediately " is easy to misread . The call to read does in fact return immediately . Any read data is returned asynchronously . Please rework this sentence .
Paragraph (version A):
Originally, sockets 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 sockets 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 A):
In contrast to sockets, 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 completes 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 results in an asynchronous send error
as an event.
Paragraph (version B):
Originally, sockets 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 sockets 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 sockets, 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.
Draft: draft-ietf-taps-interface

Commentary: The concept of cloning is used in the overview without introduction . I 've suggested an earlier discussion of it in the architecture document , which would help , but even in this document , there should be an introduction or forward reference .
Paragraph (version A):
Explicit support for multistreaming and multipath transport
protocols, and the grouping of related Connections into Connection
Groups through cloning of Connections.  This allows applications
to take full advantage of new transport protocols supporting these
features.
Paragraph (version B):
Explicit support for multistreaming and multipath transport
protocols, and the grouping of related Connections into Connection
Groups through "cloning" of Connections (see groups).  This
function allows applications to take full advantage of new
transport protocols supporting these features.
Draft: draft-ietf-taps-interface

Commentary: At the end of the API summary , there 's a paragraph that looks like a " Structure of this document " discussion - should it be in a different place ? The list in the paragraph is odd - why is Section 8 , for instance , not in the list ?
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 (Pre-Establishment, Establishment, Data Transfer, and
Termination) described in Section 4.1 of I-D.ietf-taps-arch.
Draft: draft-ietf-taps-arch

Commentary: Describe what you mean by racing earlier in the document - the use in the Introduction is bare . 
 As said .
Paragraph (version A):
The goal of the Transport Services architecture is to provide a
common, flexible, and reusable interface for transport protocols.  As
applications adopt this interface, they will benefit from a wide set
of transport features that can evolve over time, and ensure 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 also support
applications by offering racing and fallback mechanisms, which
otherwise need to be implemented in each application separately.
Paragraph (version B):
The goal of the Transport Services architecture is to provide a
common, flexible, and reusable interface for transport protocols.  As
applications adopt this interface, they will benefit from a wide set
of transport features that can evolve over time, and ensure 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 also support
applications by offering racing mechanisms (attempting multiple IP
addresses, protocols, or network paths in parallel), which otherwise
need to be implemented in each application separately (see racing).
Draft: draft-ietf-taps-interface

Commentary: Reading 7.3.2 I found the concepts there quite abstract . I think it would really help to be a bit more specific and e.g. take UDP and TCP as examples basically saying some like : as UDP is consider a message based protocol , each received datagram will trigger receive ( ) of a complete message . As TCP is stream - based all TCP segments will be delivered by  ( ) . 
 My impression here is that we could use some examples for different protocols for sending and receiving ( for messages , datagrams , and raw streams ) . This could be a 7.4 Examples section . 
 Do we need to do this - can we just close this ? 
 I think it 's still valuable to have an example of ReceivedPartial somewhere . 
 The  example is good . I think we may need clarification that Received can support object - based rather than just byte - array - based responses . 
 LGMT
Paragraph (version B):
In the following example, an application only wants to receive up to
1000 bytes at a time from a Connection.  If a 1500-byte message
arrives, it would receive the message in two separate ReceivedPartial
events.
Draft: draft-ietf-taps-arch

Commentary:  's attempt to improve preconnection ( ) 
 The big paragraph that is the first bullet of section 4.1.2 does n't read well . Pleas consider restructuring it , and simplifying the sentences as much as possible . 
 I think this reads better
Paragraph (version A):
Preconnection: A Preconnection object is a representation of a
potential Connection.  It has state that describes parameters of a
Connection that might exist in the future: the Local Endpoint from
which that Connection will be established, the Remote Endpoint
(preestablishment) to which it will connect, and Transport
Properties that influence the paths and protocols a Connection
will use.  A Preconnection can be fully specified such that it
represents a single possible Connection, or it can be partially
specified such that it represents a family of possible
Connections.  The Local Endpoint (preestablishment) is required if
the Preconnection is used to Listen for incoming Connections.  The
Local Endpoint is optional if it is used to Initiate Connections.
The Remote Endpoint is required in the Preconnection that is used
to Initiate Connections.  The Remote Endpoint is optional if it is
used to Listen for incoming Connections.  The Local Endpoint and
the Remote Endpoint are both required if a peer-to-peer Rendezvous
is to occur based on the Preconnection.
Paragraph (version B):
Preconnection: A Preconnection object is a representation of a
Connection that has not yet been established.  It has state that
describes parameters of the Connection: the Local Endpoint from
which that Connection will be established, the Remote Endpoint
(preestablishment) to which it will connect, and Transport
Properties that influence the paths and protocols a Connection
will use.  A Preconnection can be either fully specified
(representing a single possible Connection), or it can be
partially specified (representing a family of possible
Connections).  The Local Endpoint (preestablishment) is required
for a Preconnection used to Listen for incoming Connections, but
optional if it is used to Initiate a Connection.  The Remote
Endpoint is required in a Preconnection that used to Initiate a
Connection, but is optional if it is used to Listen for incoming
Connections.  The Local Endpoint and the Remote Endpoint are both
required if a peer-to-peer Rendezvous is to occur based on the
Preconnection.
Draft: draft-ietf-taps-impl

Commentary: Added something directly from RFC8085 that UDP can be connected in a sense . 
 If this is any help , RFC8085 said : " Many operating systems also allow a UDP socket to be connected , i.e. , to bind a UDP socket to a specific pair of addresses and ports . This is similar to the corresponding TCP sockets API functionality . However , for UDP , this is only a local operation that serves to simplify the local send / receive functions and to filter the traffic for the specified addresses and ports . " 
 Added text in
Paragraph (version A):
Once the Connection is established, its interface maps actions and
events to the details of the chosen Protocol Stack.  For example, the
same Connection object may ultimately represent a single instance of
one transport protocol (e.g., a TCP connection, a TLS session over
TCP, a UDP flow with fully-specified Local and Remote Endpoints, a
DTLS session, a SCTP stream, a QUIC stream, or an HTTP/2 stream).
The properties held by a Connection or Listener is independent of
other connections that are not part of the same Connection Group.
Once Initate has been called, the Selection Properties and Endpoint
information are immutable (i.e, an application is not able to later
modify Selection Properties on the original Preconnection object).
Listener objects are created with a Preconnection, at which point
their configuration should be considered immutable by the
implementation.  The process of listening is described in listen.
Paragraph (version B):
Once the Connection is established, its interface maps actions and
events to the details of the chosen Protocol Stack.  For example, the
same Connection object may ultimately represent a single instance of
one transport protocol (e.g., a TCP connection, a TLS session over
TCP, a UDP flow with fully-specified Local and Remote Endpoints, a
DTLS session, a SCTP stream, a QUIC stream, or an HTTP/2 stream).
The properties held by a Connection or Listener is independent of
other connections that are not part of the same Connection Group.
Paragraph (version B):
Connection establishment is only a local operation for a Datagram
transport (e.g., UDP(-Lite)), which serves to simplify the local
send/receive functions and to filter the traffic for the specified
addresses and ports RFC8085.
Paragraph (version B):
Once Initiate has been called, the Selection Properties and Endpoint
information are immutable (i.e, an application is not able to later
modify Selection Properties on the original Preconnection object).
Listener objects are created with a Preconnection, at which point
their configuration should be considered immutable by the
implementation.  The process of listening is described in listen.