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

Commentary: Thank you !
Paragraph (version A):
Message Property: A property than can be used to specify details
about Message transmission, or obtain details about the
transmission after receiving a Message.
Paragraph (version B):
Message Property: A property that can be used to specify details
about Message transmission, or obtain details about the
transmission after receiving a Message.
Paragraph (version A):
Preconnection: an object that repesents a Connection that has not
yet been established.
Paragraph (version B):
Preconnection: an object that represents a Connection that has not
yet been established.
Paragraph (version A):
The Transport Services implementation I-D.ietf-taps-impl implements
the transport layer protocols and other functions needed to send and
receive data.  It is is responsible for mapping the API to a specific
available transport protocol stack and managing the available network
interfaces and paths.
Paragraph (version B):
The Transport Services implementation I-D.ietf-taps-impl implements
the transport layer protocols and other functions needed to send and
receive data.  It is responsible for mapping the API to a specific
available transport protocol stack and managing the available network
interfaces and paths.
Paragraph (version A):
Using asynchronous events allows for a more natural interaction model
when establishing connections and transferring data.  Events in time
more closely reflect the nature of interactions over networks, as
opposed to how the Socket API represent network resources as file
system objects that may be temporarily unavailable.
Paragraph (version B):
Using asynchronous events allows for a more natural interaction model
when establishing connections and transferring data.  Events in time
more closely reflect the nature of interactions over networks, as
opposed to how the Socket API represents network resources as file
system objects that may be temporarily unavailable.
Paragraph (version A):
Applications using the Transport Services API are REQUIRED to be
robust to the automated selection provided by the Transport Services
implementation.  This automated selection is constrained by the
properties and preferences expressed by the application and requires
applications to explictly set properties that define any necssary
constraints on protocol, path, and interface selection.
Paragraph (version B):
Applications using the Transport Services API are REQUIRED to be
robust to the automated selection provided by the Transport Services
implementation.  This automated selection is constrained by the
properties and preferences expressed by the application and requires
applications to explicitly set properties that define any necessary
constraints on protocol, path, and interface selection.
Draft: draft-ietf-taps-arch

Commentary: Feel free to approve or propose changes to improve this sentence in  . 
 BT : " I ’m not convinced of the value of the glossary of terms , as it forwardrefs basically the entire document , and some of the definitions are so generic as to be potentially confusing ( e.g. Event ) , so I think putting these up front reduces the document ’s approachability and readability . I understand that some people like these ( and other standards orgs make them mandatory , hi ETSI ) , so I wo n’t fight it . " " Adding a sentence making it clear it ’s safe to skip the glossary if you ’re going to read the rest of the document would address my approachability concern completely . "
Paragraph (version A):
This subsection provides a glossary of key terms related to the
Transport Services architecture.  It provides a simple description of
key terms that are later defined in this document.
Paragraph (version B):
This subsection provides a glossary of key terms related to the
Transport Services architecture.  It provides a short description of
key terms that are later defined in this document.
Draft: draft-ietf-taps-arch

Commentary: ( sorry that it took me so long ) This uses some text that is also in the interface draft . 
 This I would like us to discuss . Well I know we have discussed this before . As I am reading the  document after a long while and having read it along with the architecture document , I kind of strongly feel that the architecture document lack of description on framer and the states . These are mentioned and pictured in the architecture document but have n't been clear there . Hence , I kind of feel that we need to move this two sections to architecture document . Please discuss so that I can understand the reasoning of not doing so . 
 Regarding section 9.1.2 , the framer description : I think it 's good to be clear and complete in the API document , but I agree that framers should be appropriately described in the architecture document . I have the impression that the text in the -arch document on this matter may indeed be too short , while the text in the -interface document may be too long ( although a little bit of repetition surely wo n't hurt here , it 's good for this document to be understandable and clear on its own ) . Maybe some of it could be moved to -arch , or repeated there ? Regarding section 11 , Connection states : to me , this is fine as it is . Section 4.1 / figure 4 in the architecture document make state transitions pretty clear - and section 11 / figure 2 are just a more fine - grain look at these states as a way to explain exactly which Events will occur when . This seems needed in the API document , where all other Events and Actions are defined , and I would think that this is at a too detailed / fine - grain level for the architecture document . 
 after giving it some more thoughts , I think your suggested approach should be fine , meaning we put more description of framer in the architecture document and leave the connection states to the  document . 
 did you want to take a stab at this ? 
 Looks great !
Paragraph (version A):
Framer: A Framer is a data translation layer that can be added to
a Connection to define how application-layer Messages are
transmitted over a Protocol Stack.  This is particularly relevant
when using a protocol that otherwise presents unstructured
streams, such as TCP.
Paragraph (version B):
Framer: A Framer is a data translation layer that can be added to
a Connection.  Framers allow extending a Connection's protocol
stack to define how to encapsulate or encode outbound Messages,
and how to decapsulate or decode inbound data into Messages.  In
this way, message boundaries can be preserved when using a
Connection object, even with a protocol that otherwise presents
unstructured streams, such as TCP.  This is designed based on the
fact that many of the current application protocols evolved over
TCP, which does not provide message boundary preservation, and
since many of these protocols require message boundaries to
function, each application layer protocol has defined its own
framing.  For example, when an HTTP application sends and receives
HTTP messages over a byte-stream transport, it must parse the
boundaries of HTTP messages from the stream of bytes.
Draft: draft-ietf-taps-arch

Commentary: In this section - can we be clear on stating what properties we are taking about and what the caches . see the first line of the section . the second paragraph should at least mention why the connection is cloned . We have n't introduced the cloning before . we need to discuss the relation with Connection Context , does a Connection group have same connection context ? My current understanding is if the Connection Context is separate then those Connections wo nt be grouped . But I fear that this can create confusion . 
 Latest merged master fixes bullet 2 . The others need new text . 
 LGTM ! Many thanks for doing this
Paragraph (version A):
A Connection Group is a set of Connections that shares properties and
caches.  A Connection Group represents state for managing Connections
within a single application, and does not require end-to-end protocol
signaling.  For multiplexing transport protocols, only Connections
within the same Connection Group are allowed to be multiplexed
together.
Paragraph (version B):
A Connection Group is a set of Connections that shares Connection
Properties and cached state generated by protocols.  A Connection
Group represents state for managing Connections within a single
application, and does not require end-to-end protocol signaling.  For
multiplexing transport protocols, only Connections within the same
Connection Group are allowed to be multiplexed together.
Paragraph (version A):
While Connection Groups are managed by the Transport Services system,
an application can define Connection Contexts to control caching
boundaries, as discussed in conn-context.
Paragraph (version B):
While Connection Groups are managed by the Transport Services system,
an application can define different Connection Contexts for different
Connection Groups to explicitly control caching boundaries, as
discussed in conn-context.
Draft: draft-ietf-taps-arch

Commentary: Unless there is a description the figure , with directed and non - directed lines it is very hard to interpret the figure . I would recommend to at least add some reading guidance for the lines . 
 LGTM , thanks!Looks fine .
Paragraph (version B):
In this diagram, the lifetime of a Connection object is broken into
three phases: Pre-Establishment, the Established state, and
Termination.
Paragraph (version B):
Pre-Establishment is based around a Preconnection object, that
contains various sub-objects that describe the properties and
parameters of desired Connections (Local and Remote Endpoints,
Transport Properties, and Security Parameters).  A Preconnection can
be used to start listening for inbound connections, in which case a
Listener object is created, or can be used to establish a new
connection directly using Initiate() (for outbound connections) or
Rendezvous() (for peer-to-peer connections).
Paragraph (version B):
Once a Connection is in the Established state, an application can
send and receive Message objects, and receive state updates.
Paragraph (version B):
Closing or aborting a connection, either locally or from the peer,
can terminate a connection.
Draft: draft-ietf-taps-arch

Commentary: Responding to review and tighter wording for the  draft : Undefined " transport object " 
 Where is this transport object defined ?
Paragraph (version A):
Event Handling (events) defines categories of notifications that
an application can receive during the lifetime of transport
objects.  Events also provide opportunities for the application to
interact with the underlying transport by querying state or
updating maintenance options.
Paragraph (version B):
Event Handling (events) defines categories of notifications that
an application can receive during the lifetime of a Connection.
Events also provide opportunities for the application to interact
with the underlying transport by querying state or updating
maintenance options.
Draft: draft-ietf-taps-arch

Commentary: Do n't just rely on the cache . 
 I think we should be very specific that the application SHOULD not expect certain caching behavior or MAY expect a minimum set of information cached . This is also related to the expectancy from application to expect same protocol given same properties and security parameter each time . will such input generate same consistent out put from one TAPS system ? 
 I suggest adding this explicitly - something like : This caching does not imply that the same decisions are necessarily made for subsequent connections , rather , it means that cached state is used by the Transport Services architecture to inform functions such as choosing the candidates to be raced , selecting appropriate transport parameters , etc . 
 See PR on request required properties , which could close this issue . 
 Thought resolved by merged PR in latest editor version . 
 Does the merged text in master address issue ? 
 LGTM , Thansk . 
 Very nice ( IMHO ) !
Paragraph (version A):
any requid or desired properties via the Transport Services API.
Paragraph (version B):
any required or desired properties via the Transport Services API.
Draft: draft-ietf-taps-arch

Commentary: /transport/ should be /connection state/ 
 This resolves one small part of  's review . 
 These comments are good to be addressed to improve the document , however , they can be done as part of IETF last call as well 
 Fixes proposed in PRs , , , , 
 LGTM
Paragraph (version A):
Termination (termination) focuses on the methods by which data
transmission is stopped, and state is torn down in the transport.
Paragraph (version B):
Termination (termination) focuses on the methods by which data
transmission is stopped, and connection state is torn down.
Draft: draft-ietf-taps-interface

Commentary: I 'm happy to do this ! But while we 're at it , is n't the " a " a bit awkward ? Would n't this read even better as : " An Endpoint MUST NOT be configured with multiple identifiers of the same type . " I just pushed that suggestion . 
 This seems to me as a strong claim without using normative language . Shall we use normative language here ? 
  , although then I think we need to explain " set " so that we create an RFC2119 sentence with meaning when read on its own . Is this anywhere near : An Endpoint MUST NOT set multiple identifiers of the same type . And ... is the /that is/ correct ? or is this an example of something that is not allowed ? 
 I 'd say it 's an example , although also the most likely such case . Suggest : replace " That is , " with " Thus , " 
 If this is just an example then lets just be explicit about it . 
 I like the change . Is the English clunky , could it be : An Endpoint MUST NOT be configured with multiple identifiers of a same type .
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.  Note that multiple Remote Endpoints can be added to a
Preconnection, as discussed in add-endpoints.
Paragraph (version B):
An Endpoint MUST NOT be configured with multiple identifiers of the
same type.  For example, 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-impl

Commentary: I think we should add a similar ranking consideration description as we have for Network paths . Otherwise , I am not sure how to rank the protocol option . 
 I think here as well that the options should be ranked based on preference , system policy , and performance . I made a pull request to add it . 
 LGTM , lets of others have any opinion about it .. 
 I agree with 
 WFM
Paragraph (version A):
This approach is commonly used for connections with optional proxy
server configurations.  A single connection might have several
options available: an HTTP-based proxy, a SOCKS-based proxy, or no
proxy.  These options should be ranked and attempted in succession.
Paragraph (version B):
This approach is commonly used for connections with optional proxy
server configurations.  A single connection might have several
options available: an HTTP-based proxy, a SOCKS-based proxy, or no
proxy.  As above, these options should be ranked based on preference,
system policy, and performance and attempted in succession.
Draft: draft-ietf-taps-arch

Commentary: Here it seems we are defining " equivalent " twice . I would rather write - Equivalent Protocol Stacks are defined as stacks that can provide the same Transport Properties and interface expectations as requested by the application . and the equivalent stacks can be swapped or raced . Also in the example - it is not clear that swapping and racing in important , however , application provided properties are . Apart from this I also think the title and content is mismatching . I found the last paragraph talking about swapping and racing focusing on security . Here we are imposing requirements on swapping and racing . These are very important for the security consideration and to me should get its own title and section separated from selection of equivalence . 
 LGTM!Looks good
Paragraph (version A):
A Transport Services implementation can select Protocol Stacks based
on the Selection and Connection Properties communicated by the
application, along with any security parameters.  If two different
Protocol Stacks can be safely swapped, or raced in parallel (see
racing), then they are considered to be "equivalent".  Equivalent
Protocol Stacks are defined as stacks that can provide the same
Transport Properties and interface expectations as requested by the
application.
Paragraph (version B):
A Transport Services implementation can attempt and select between
multiple Protocol Stacks based on the Selection and Connection
Properties communicated by the application, along with any security
parameters.  The implementation can only attempt to use multiple
Protocol Stacks when they are "equivalent", which means that the
stacks can provide the same Transport Properties and interface
expectations as requested by the application.  Equivalent Protocol
Stacks can be safely swapped or raced in parallel (see racing) during
connection establishment.
Draft: draft-ietf-taps-arch

Commentary: Assuming there would be more protocols in the future and the minset functionalities will expand via extension or amendments . It would important to indicate if this architecture should is also extensible or it only supports on the minimum set referred . Definitely we have n't seen the future yet , but it would be important to express if we have considered such expansion of minimum functionalities . 
 To me , the current spec is based on minset that describes the common functions . So , the addition I would expect here is to say that there can be extensions and protocol - specific features . 
 I expect that if a common feature is to the minset , then the architecture and API surface would also be extended to match . 
 LGTM modulo a nit
Paragraph (version A):
Any functionality that is common across multiple transport protocols
SHOULD be made accessible through a unified set of calls using the
Transport Services API.  As a baseline, any Transport Services API
SHOULD 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 calls using the
Transport Services API.  As a baseline, any Transport Services API
SHOULD allow access to the minimal set of features offered by
transport protocols RFC8923.  If that minimal set is updated or
expanded in the future, the Transport Services API ought to be
extended to match.
Draft: draft-ietf-taps-arch

Commentary: If an application wishes to use a special feature then if might need to adjust itself if that special feature is not applicable to the Connection Object it gets/ gets created for . Should there be no requirement(at least recommendation ) on getting this information back ? The application can ask a specialized feature in a way that it gets what it wants or the communication MUST fail . In such case the should be a requirement on the application to be specific about it or ? 
 The API solves this in two ways : We have a preference - type that allows the application to explicitly state that it requires / prefers / does - not - care / wants - to - avoid / prohibits each feature . After the establishment , the application can query each feature and gets a boolean back whether it is present or not . Should we add this as a forward reference here or at least hint at the solution ? 
 Hint at the solution sounds like a very good approach to me .
Paragraph (version B):
To control these specialized features, the application can declare
its preference - whether the presence of a specific feature is
prohibited, should be avoided, can be ignored, is preferred, or is
required in the Pre-Establishment phase.  An implementation of a
Transport Services API would honor this preference and allow the
application to query the availability of each specialized feature
after a successful establishment.
Draft: draft-ietf-taps-interface

Commentary: thanks for the shepherd review
Paragraph (version A):
The Transport Services API provides two properties to allow a sender
to signal the relative priority of data transmission: "msgPriority"
msg-priority and "connPriority" conn-priority.  These properties are
designed to allow the expression and implementation of a wide variety
of approaches to transmission priority in the transport and
application layer, including those which do not appear on the wire
(affecting only sender-side transmission scheduling) as well as those
that do (e.g.  I-D.ietf-httpbis-priority.
Paragraph (version B):
The Transport Services API provides two properties to allow a sender
to signal the relative priority of data transmission: "msgPriority"
msg-priority and "connPriority" conn-priority.  These properties are
designed to allow the expression and implementation of a wide variety
of approaches to transmission priority in the transport and
application layer, including those which do not appear on the wire
(affecting only sender-side transmission scheduling) as well as those
that do (e.g.  RFC9218.
Draft: draft-ietf-taps-impl

Commentary: Takes care of part of .
Paragraph (version A):
The Transport Services API mappings for MPTCP are identical to TCP.
MPTCP adds support for multipath properties, such as "multipath" and
"multipathPolicy".
Paragraph (version B):
The Transport Services API mappings for MPTCP are identical to TCP.
MPTCP adds support for multipath properties, such as "multipath" and
"multipathPolicy", and actions for managing paths, such as
"AddRemote" and "RemoveRemote".
Draft: draft-ietf-taps-impl

Commentary: Initially I thought the description for UDP - Lite was incomplete , but mapping back to the details of the API draft I realized it was incorrect . UDP - Lite supports the msgChecksumLen and recvChecksumLen properties . The API for theses primitives is a bit messy . As specified I think it means the following : UDP can use them to set full coverage or no checksum using the special value of 0 . UDP - Lite can use them to set full coverage or a partial coverage . Setting the checksum to only cover the header , although supported by UDP - Lite , will not be possible as 0 is a special value . The special value of 0 can not be used by UDP - Lite , but I left this detail out of the pull request as I thought it got very detailed . It can be if you think it is needed .
Paragraph (version A):
The Transport Services API mappings for UDP-Lite are identical to
UDP.  Properties that require checksum coverage are not supported by
UDP-Lite, such as "msgChecksumLen", "fullChecksumSend",
"recvChecksumLen", and "fullChecksumRecv".
Paragraph (version B):
The Transport Services API mappings for UDP-Lite are identical to
UDP.  In addition, UDP-Lite supports the "msgChecksumLen" and
"recvChecksumLen" Properties that allow an application to specify the
minimum number of bytes in a message that need to be covered by a
checksum.