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

Commentary: So , for a multiplexing protocol ( SCTP , QUIC ) , CloseGroup and AbortGroup has a specific meaning to treat the group vs a single connection / stream . For TCP / UDP I wrote it to be a no - op , but I can say that it affects any other connections that were cloned out ? But I wonder if that might be a little weird too . 
 I think we need the system to treat it that way for consistency . Clearly , for a mux'ing protocol this is the obvious choice - but the application is not aware of the protocol below ... so if it creates a group of TCP connections , with or without congestion control coupling , it will expect : that changing a connection property on one of the connections will affect the others ( so that also must be implemented - because it WILL happen with a mux'ing protocol ) , that closing the group will close them all . Imagine an application getting QUIC once , and not getting it another time ... surely we need a consistent behavior towards the app for both of these cases ? 
 sounds good , please check the updated text ( or suggest text if you have further ideas ! ) 
 This is probably fine as is , but I suggested alternative phrasing which might be even more clear . Great , thanks!!LGTM with the updates , thanks !
Paragraph (version B):
Calling "CloseGroup" on a TCP Connection (CLOSE.TCP) is identical
to calling "Close" on this Connection and on all Connections in
the same ConnectionGroup.
Paragraph (version B):
Calling "AbortGroup" on a TCP Connection (ABORT.TCP) is identical
to calling "Abort" on this Connection and on all Connections in
the same ConnectionGroup.
Paragraph (version B):
Calling "CloseGroup" 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 B):
Calling "CloseGroup" on a UDP Multicast Receive Connection
(ABORT.UDP(-Lite)) is identical to calling "Close" on this
Connection and on all Connections in the same ConnectionGroup.
Paragraph (version B):
Calling "AbortGroup" on a UDP Multicast Receive Connection
(ABORT.UDP(-Lite)) is identical to calling "Close" on this
Connection and on all Connections in the same ConnectionGroup.
Paragraph (version B):
CloseGroup: Calling "CloseGroup" calls CLOSE.SCTP, closing all
Connections in the SCTP association.
Paragraph (version B):
AbortGroup: Calling "AbortGroup" calls ABORT.SCTP, immediately
closing all Connections in the SCTP association.
Draft: draft-ietf-taps-interface

Commentary: 2 from this . Is s6.3.2 supposed to be about certificate path validation ? It might be worth explicit saying that and providing a reference to RFC 5280 ? Note that I do not have a proposed solution ( yet ) . 
 Yes , we should reference RFC 5280 here .
Paragraph (version A):
Trust verification callback: Invoked when a Remote Endpoint's
trust must be validated before the handshake protocol can
continue.
Paragraph (version B):
Trust verification callback: Invoked when a Remote Endpoint's
trust must be verified before the handshake protocol can continue.
For example, the application could verify an X.509 certificate as
described in RFC5280.
Draft: draft-ietf-taps-impl

Commentary: In the impl draft , I 'm supposed to build a tree based on , in order ( 1 ) " path " : AFAICT this means " interface " . The -api draft provides in interface preference framework in 4.2.11 . ( BTW if it really means interface maybe we should say ' interface ' ) . ( 2 ) Protocol : almost all of 4.2 in -api explains how to express this . ( with an assist in -impl 4.1.3 explaining how to handle PREFER vs. AVOID ) ( 3 ) " derived endpoint " I gather this is basically multiple addresses coming back from remote endpoint resolution . But where is the construct in -api that allows applications to express a preference here ? 
 I 'm not sure we want to add anything to the API here . There are existing preferences that can bias towards IPv6 , such as preferring or requiring . I think we can just detail that in the implementation draft . 
 Thanks , LGTM !
Paragraph (version B):
Applications can influence which derived endpoints are allowed and
preferred via Selection Properties set on the Preconnection.  For
example, setting a preference for "useTemporaryLocalAddress" would
prefer the use of IPv6 over IPv4, and requiring
"useTemporaryLocalAddress" would eliminate IPv4 options, since IPv4
does not support temporary addresses.
Draft: draft-ietf-taps-impl

Commentary: Preconnections are mutable , until they are not . The second paragraph of section 2 states " bundles of properties an application can both read and write " , which seems to conflict with this .  should lead with the fact of mutable mutability over the preconnection lifecycle , not " is mutable " . 
 The Connection / Listener makes a deep copy that is now immutable , but the original object is still mutable .
Paragraph (version A):
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 not affected when
the application makes changes to a Preconnection object.  This may
involve the implementation performing a deep-copy, copying the object
with all the objects that it references.
Paragraph (version B):
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 cannot be mutated by
the application making changes to the original Preconnection object.
This may involve the implementation performing a deep-copy, copying
the object with all the objects that it references.
Draft: draft-ietf-taps-impl

Commentary: It seems blindingly obvious to me that an implementation would need to take care of this ... and this note of caution seems quite appropriate ( if unnecessary ... but surely it does n't hurt ) . 
 Dynamic framer add and passthrough ( last two paragraphs of section 6.1 ) assume synchronous operation ; what happens to bytes in the send / receive buffers when the framer stack changes ? There either needs to be an explicit mutex here ( allowing the framer / implementation to lock the buffers at the exact point the framer change happens , not allowing any bytes to be processed while the dynamic framer decision is made ) , or some way to annotate in a buffer the replay point after which a dynamic reframing is necessary . Are we going to leave this up to implementors to figure out , or should we point out that here be dragons ? 
 We should clarify that these operations within the data path of the stack should be synchronized .
Paragraph (version B):
The Transport Services implementation needs to ensure that all of the
events and actions taken on a Message Framer are synchronized to
ensure consistent behavior.  For example, some of the actions defined
below (such as PrependFramer and StartPassthrough) modify how data
flows in a protocol stack, and require synchronization with sending
and parsing data in the Message Framer.
Draft: draft-ietf-taps-interface

Commentary: As noted in the issue unsure if you also want to add a reference to for ICE . 
 15 from this . Trimmed to only outdated references because the outdated ones will be auto - fixed with a new version of -implementation . What follows are the I - D nits references to check . Some of these might be on purpose : * * Obsolete normative reference : RFC 4941 ( Obsoleted by RFC 8981 ) -- Obsolete informational reference ( is this intentional ? ): RFC 5245 ( Obsoleted by RFC 8445 , RFC 8839 ) NOTE : The PR only replaced 5245 with 8445 . Unsure if you should also want to add a reference to 8839 . -- Obsolete informational reference ( is this intentional ? ): RFC 5766 ( Obsoleted by RFC 8656 )
Paragraph (version A):
This property allows the application to express a preference for the
use of temporary local addresses, sometimes called "privacy"
addresses RFC4941.  Temporary addresses are generally used to prevent
linking connections over time when a stable address, sometimes called
"permanent" address, is not needed.  There are some caveats to note
when specifying this property.  First, if an application Requires the
use of temporary addresses, the resulting Connection cannot use IPv4,
because temporary addresses do not exist in IPv4.  Second, temporary
local addresses might involve trading off privacy for performance.
For instance, temporary addresses can interfere with resumption
mechanisms that some protocols rely on to reduce initial latency.
Paragraph (version B):
This property allows the application to express a preference for the
use of temporary local addresses, sometimes called "privacy"
addresses RFC8981.  Temporary addresses are generally used to prevent
linking connections over time when a stable address, sometimes called
"permanent" address, is not needed.  There are some caveats to note
when specifying this property.  First, if an application Requires the
use of temporary addresses, the resulting Connection cannot use IPv4,
because temporary addresses do not exist in IPv4.  Second, temporary
local addresses might involve trading off privacy for performance.
For instance, temporary addresses can interfere with resumption
mechanisms that some protocols rely on to reduce initial latency.
Paragraph (version A):
If there are multiple Local Endpoints or Remote Endpoints configured,
then initiating a Rendezvous() action will systematically probe the
reachability of those endpoint candidates following an approach such
as that used in Interactive Connectivity Establishment (ICE) RFC5245.
Paragraph (version B):
If there are multiple Local Endpoints or Remote Endpoints configured,
then initiating a Rendezvous() action will systematically probe the
reachability of those endpoint candidates following an approach such
as that used in Interactive Connectivity Establishment (ICE) RFC8445.
Draft: draft-ietf-taps-interface

Commentary: I can change that . I was trying to just copy the text from 8.1.11.1 . I guess I would change it there too . Stand by . 
 8 from this . Are these sizes in bytes too like 8.1.11.1 ? 
 Could this better worded as " specified as the number of bytes " ?
Paragraph (version A):
This property represents the maximum Message size that can be sent
before or during Connection establishment, see also msg-
safelyreplayable.  It is given in Bytes.
Paragraph (version B):
This property represents the maximum Message size that can be sent
before or during Connection establishment, see also msg-
safelyreplayable.  It is specified as the number of bytes.
Paragraph (version A):
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 B):
This property, if applicable, represents the maximum Message size
that can be sent without incurring network-layer fragmentation at the
sender.  It is specified as the number of bytes.  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):
This property represents the maximum Message size that an application
can send.
Paragraph (version B):
This property represents the maximum Message size that an application
can send.  It is specified as the nummber of bytes.
Paragraph (version A):
This numeric property represents the maximum Message size that an
application can receive.
Paragraph (version B):
This numeric property represents the maximum Message size that an
application can receive.  It specified as the number of bytes.
Draft: draft-ietf-taps-interface

Commentary: The other option is to tell people to prepend the name of the framer to the property name . 
 Is the " scope " used for message contexts ( 9.1.1 ) ever anything but a framer ? If not , could this section just say framer ? 
 We believe that it is the same ; if so , " scope " should probably indeed be named " framer " .  , could you please check ? 
 I find this a little strange : given that we do have optional parameters , what 's the benefit of first introducing the " add " and " get " calls as if the " framer " parameter did n't exist , and then later changing that ? It would seem more consistent to me to introduce it where you had the scope parameter before , called " framer " , and use a forward reference to say that framers will be explained later .
Paragraph (version A):
To get or set Message Properties, the optional scope parameter is
left empty.  To get or set meta-data for a Framer, the application
has to pass a reference to this Framer as the scope parameter.
Paragraph (version B):
These Message Properties may be generic properties or Protocol
Specific Properties.
Paragraph (version A):
When sending Messages, applications can add Framer-specific key/value
pairs to a MessageContext (msg-ctx).  This mechanism can be used, for
example, to set the type of a Message for a TLV format.  The
namespace of values is custom for each unique Message Framer.
Paragraph (version B):
When sending Messages, applications can add Framer-specific
properties to a MessageContext (msg-ctx).  In order to set these
properties, the "add" and "get" actions on the MessageContext.  To
avoid naming conflicts, the property names SHOULD be prefixed with a
namespace referencing the framer implementation or the protocol it
implements as described in property-names.
Paragraph (version B):
This mechanism can be used, for example, to set the type of a Message
for a TLV format.  The namespace of values is custom for each unique
Message Framer.
Draft: draft-ietf-taps-impl

Commentary: Fix to Issue 
 We do n’t mention layers in the text before : “ A violation of any of the layers should cause ” Is this better as : ” A violation that occurs at any of the policer layers should cause ” 
 Fixed
Paragraph (version A):
In general, any protocol or path used for a connection must conform
to all three sources of constraints.  A violation of any of the
layers should cause a protocol or path to be considered ineligible
for use.  For an example of application preferences leading to
constraints, an application may prohibit the use of metered network
interfaces for a given Connection to avoid user cost.  Similarly, the
system policy at a given time may prohibit the use of such a metered
network interface from the application's process.  Lastly, the
implementation itself may default to disallowing certain network
interfaces unless explicitly requested by the application and allowed
by the system.
Paragraph (version B):
In general, any protocol or path used for a connection must conform
to all three sources of constraints.  A violation that occurs at any
of the policy layers should cause a protocol or path to be considered
ineligible for use.  For an example of application preferences
leading to constraints, an application may prohibit the use of
metered network interfaces for a given Connection to avoid user cost.
Similarly, the system policy at a given time may prohibit the use of
such a metered network interface from the application's process.
Lastly, the implementation itself may default to disallowing certain
network interfaces unless explicitly requested by the application and
allowed by the system.
Draft: draft-ietf-taps-interface

Commentary: I think there 's a need for more discussion and clarity around the restriction that " An Endpoint can not have multiple identifiers of a same type set . " Why not ? You effectively are letting the endpoint have ( potentially ) multiple IP addresses when you create it with an identifier that is a DNS name . This feels like an artificial , inconsistent , restriction given the rest of the document ( look at the 3rd paragraph of 6.1 ) . 
 I think the right thing to do is to delete " An Endpoint can not have multiple identifiers of a same type set . That is , an endpoint can not have two IP addresses specified . Two separate IP addresses are represented as two Endpoint Objects . " ; if you agree , please do so . 
 I do n't agree that we should delete this . This has been a quite important point in our experience with the API . To make the system work well , resolution should be handled by the TAPS system . If you want to connect by a hostname , provide the hostname — don't try to cache the addresses ( often incorrectly ) and just pass the same set of addresses again . Note that this does n't stop multiple addresses from being to a preconnection . We have this example : Just , one endpoint is a single identifier . You can pass multiple if you want multiple . 
 Does this mean the API ca n't distinguish a remote endpoint that 's known to be a single interface with two IP addresses assigned , which would have to be passed as two objects , from two remote endpoints each with a single interface ? There 's no way of saying " these two IP addresses are known to be the same remote interface " ? If so , does this matter ?
Paragraph (version A):
An Endpoint cannot have multiple identifiers of a same type set.
That is, an endpoint cannot have two IP addresses specified.  Two
separate IP addresses are represented as two Endpoint Objects.  If a
Preconnection specifies a Remote Endpoint with a specific IP address
set, it will only establish Connections to that IP address.  If, on
the other hand, the Remote Endpoint specifies a hostname but no
addresses, the Connection can perform name resolution and attempt
using any address derived from the original hostname of the Remote
Endpoint.
Paragraph (version B):
An Endpoint cannot have multiple identifiers of a same type set.
That is, an endpoint cannot have two IP addresses specified.  Two
separate IP addresses are represented as two Endpoint Objects.  If a
Preconnection specifies a Remote Endpoint with a specific IP address
set, it will only establish Connections to that IP address.  If, on
the other hand, the Remote Endpoint specifies a hostname but no
addresses, the Connection can perform name resolution and attempt
using any address derived from the original hostname of the Remote
Endpoint.  Note that multiple Remote Endpoints can be added to a
Preconnection, as discussed in add-endpoints.
Draft: draft-ietf-taps-arch

Commentary: This is the only place multicast considerations might fit in -arch . We do n't discuss anycast at all , and I think it 's largely orthogonal to transport ( indeed , people seem to be running stateful / connection - oriented transports to anycast endpoints just fine in the Internet , even though it " does n't work " :) ) 
 Consider an explicit discussion of multicast / anycast considerations in this document .
Paragraph (version A):
Endpoint: An Endpoint represents an identifier for one side of a
transport connection.  Endpoints can be Local Endpoints or Remote
Endpoints, and respectively represent an identity that the
application uses for the source or destination of a connection.
An Endpoint can be specified at various levels of abstraction, and
an Endpoint at a higher level of abstraction (such as a hostname)
can be resolved to more concrete identities (such as IP
addresses).
Paragraph (version B):
Endpoint: An Endpoint represents an identifier for one side of a
transport connection.  Endpoints can be Local Endpoints or Remote
Endpoints, and respectively represent an identity that the
application uses for the source or destination of a connection.
An Endpoint can be specified at various levels of abstraction.  An
Endpoint at a higher level of abstraction (such as a hostname) can
be resolved to more concrete identities (such as IP addresses).
An endpoint may also represent a multicast group, in which case it
selects a multicast transport for communication.
Draft: draft-ietf-taps-interface

Commentary: There are several places where the document says " Changes to a < fooafter func ( ) has been called do not have any connection on existing < bars " . This feels like an opportunity for more clarity about what a < fooreally is . The document uses the word Object , and maybe there 's an assumption that there 's a shared understanding of what the properties of an Object are . Being explicit with something like " An Object is a collection of properties that implementations of the API read and use ... " to avoid the " here 's a chunk of memory that can get passed into the API that it can operate on , and expect the caller to see the effects of the operation " interpretation . I think what the current text is trying to say is that the user of the API should assume the implementation of the API made its own private copy of the Object at the point of the given func ( ) call and that it will not see any changes to the copy the user has at any later point . But then there 's some text that looks like " Once a < foohas been used with a func ( ) , it is invalid to modify any of its properties . " So ...
Paragraph (version A):
Actions associated with no Object are Actions on the API; they are
equivalent to Actions on a per-application global context.
Paragraph (version B):
Objects that are passed as parameters to Actions use call-by-value
behavior.  Actions associated with no Object are Actions on the API;
they are equivalent to Actions on a per-application global context.
Paragraph (version A):
Properties can be added to a MessageContext object only before the
context is used for sending.  Once a messageContext has been used
with a Send call, it is invalid to modify any of its properties.
Paragraph (version B):
Properties can be added to a MessageContext object only before the
context is used for sending.  Once a MessageContext has been used
with a Send call, further modifications to the MessageContext object
do not have any effect on this Send call.
Draft: draft-ietf-taps-interface

Commentary: Be firm , but avoid MUST NOT apply across different protocols TO ADDRESS 
 This was discussed at the Interim and final text approved by MW . 
 In section 8 's third paragraph , the MUST NOT is not a good use of 2119/8174 . Are you trying to say protocol specific property names must not be reused across different protocols ? 
 I note that the current text was : " Protocol Specific Properties are defined in a transport- and implementation - specific way , and MUST NOT apply across different protocols . Too much reliance by an application on Protocol Specific Properties can significantly reduce the flexibility of a transport services implementation . " 
 Decision : avoid this language , say " architecture expects that ... " 
 Say this is important but only recommend .
Paragraph (version A):
Protocol Specific Properties are defined in a transport- and
implementation-specific way to permit more specialized protocol
features to be used.  Too much reliance by an application on Protocol
Specific Properties can significantly reduce the flexibility of a
transport services implementation to make appropriate selection and
configuration choices.  Therefore, it is RECOMMENDED that Protocol
Properties are normnally used for properties common across different
protocols and that Protocol Specific Properties are only used where
specific protocols or properties are necessary.
Paragraph (version B):
Protocol Specific Properties are defined in a transport- and
implementation-specific way to permit more specialized protocol
features to be used.  Too much reliance by an application on Protocol
Specific Properties can significantly reduce the flexibility of a
transport services implementation to make appropriate selection and
configuration choices.  Therefore, it is RECOMMENDED that Protocol
Properties are used for properties common across different protocols
and that Protocol Specific Properties are only used where specific
protocols or properties are necessary.