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

Commentary: Satisfies 
 Okay , addressed capitalization and took  's suggested paragraph ( with one tiny change ) . 
 Fine with me - go ahead 
 any further comments on this one ? 
 ship it 
 Sorry , seems I should have clicked " approve " earlier . Still being clumsy in github :(
Paragraph (version B):
Final is a boolean property.  If true, this Message is the last one
that the application will send on a Connection.  This allows
underlying protocols to indicate to the Remote Endpoint that the
Connection has been effectively closed in the sending direction.  For
example, TCP-based Connections can send a FIN once a Message marked
as Final has been completely sent.  Protocols that do not support
signalling the end of a Connection in a given direction will ignore
this property.
Paragraph (version B):
Note that a Final Message must always be sorted to the end of a list
of Messages.  The Final property overrides Niceness and any other
property that would re-order Messages.  If another Message is sent
after a Message marked as Final has already been sent on a
Connection, the new Message will report an error.
Paragraph (version B):
The application may check a property to determine if a received
Message is the Final Message on a Connection.  For any Message that
is marked as Final, the application can assume that there will be no
more Messages received on the Connection once the Message has been
completely delivered.  This corresponds to the Final property that
may be marked on a sent Message send-final.
Paragraph (version B):
Any calls to "Receive" once the Final Message has been delivered will
result in errors.
Draft: draft-trammell-taps-interface

Commentary: See issue The one question I have here is the semantics around batching . In our implementation , we use block semantics ( from clang ) , to batch looks like : connectionbatch(^ { connectionsend ( ... ) ; connection_send ( ... ) ; } ) ; where the block is called inline , and the batch is over when the block returns . I 'm not sure what the right style for the pseudo - code is for the draft . 
 In aligning the implementation with the API for the initial draft , we removed this text since we still need text in the API : Since sending a Message may involve a context switch between the application and the transport system , sending patterns that involve multiple small Messages can incur high overhead if each needs to be enqueued separately . To avoid this , the application should have a way to indicate a batch of Send actions , during which time the implementation will hold off on processing Messages until the batch is complete . This can also help context switches when enqueuing data in the interface driver if the operation can be batched . 
 This seems equivalent to the idea of PUSH in existing systems and would make sense for lots of short write calls . 
 +1 . The higher - level question here is how to support high - performance applications . Send batching is one thing you can do here . Receive batching would be another obvious one . Zero - copy is another , though that 's probably so tied to implementation and platform that it 's not useful to standardize . But there should be some way for this interface to coexist with it ... 
 +1 from me too 
 +1 In my opinion , support for high - performance applications is nothing we can add to the API , but rather something we must sure to not prevent or make hard to implement . So we should ask ourselves for every point in the API " can this be implemented zero - copy " or " can an implementation batch this " – if the answer is no , we have to fix that . 
 this one seems to have consensus and does not seem to be too much work . if you can get a PR in in the next week or so let 's ship it with  ... 
 I 'll try to get this in soon ! 
 fixed with merge of 
 LGTM , we can worry about the right way to pseudocode this later .
Paragraph (version B):
In order to reduce the overhead of sending multiple small Messages on
a Connection, the application may want to batch several Send actions
together.  This provides a hint to the system that the sending of
these Messages should be coalesced when possible, and that sending
any of the batched Messages may be delayed until the last Message in
the batch is enqueued.
Paragraph (version B):
Since sending a Message may involve a context switch between the
application and the transport system, sending patterns that involve
multiple small Messages can incur high overhead if each needs to be
enqueued separately.  To avoid this, the application should have a
way to indicate a batch of Send actions, during which time the
implementation will hold off on processing Messages until the batch
is complete.  This can also help context switches when enqueuing data
in the interface driver if the operation can be batched.
Draft: draft-trammell-taps-interface

Commentary: Removes Immediate Acknowledgment and makes it an optional implicit feature of Low Latency profile , renames Instantaneous Capacity Profile to Transmission Profile . Addresses ; we should open a new issue to discuss whether we want to split Capacity Profile back out . 
 About " Transmission profile " , I like it ; we had Capacity Profile ( not " Instantaneous " though ) in NEAT because it contains choices about how an application wants to make use of the available capacity . Because " Transmission profile " loses that hint , it conveys less meaning - but frankly , I still prefer it just for the way it sounds .
Paragraph (version A):
The application is interactive.  Response time (latency) should be
optimized at the expense of bandwidth efficiency and delay
variation.  This can be used by the system to disable the
coalescing of multiple small Messages into larger packets (Nagle's
algorithm), to prefer lower-latency paths, signal a preference for
lower-latency, higher-loss treatment, and so on.
Paragraph (version A):
The application expects to send/receive data at a constant rate
after Connection establishment.  Delay and delay variation should
be optimized at the expense of bandwidth efficiency.  This implies
that the Connection may fail if the desired rate cannot be
maintained across the Path.  A transport may interpret this
capacity profile as preferring a circuit breaker RFC8084 to a rate
adaptive congestion controller.
Paragraph (version B):
The application expects to send/receive data at a constant rate
after Connection establishment.  Delay and delay variation should
be minimized at the expense of bandwidth efficiency.  This implies
that the Connection may fail if the desired rate cannot be
maintained across the Path.  A transport may interpret this
capacity profile as preferring a circuit breaker RFC8084 to a rate
adaptive congestion controller.
Paragraph (version A):
This boolean property specifies, if true, that an application wants
this Message to be acknowledged immediately by the receiver.  In case
of reliable transmission, this informs the transport protocol on the
sender side faster that it can remove the Message from its buffer;
therefore this property can be useful for latency-critical
applications that maintain tight control over the send buffer (see
sending).
Paragraph (version A):
Response time (latency) should be optimized at the expense of
bandwidth efficiency and delay variation when sending this
message.  This can be used by the system to disable the coalescing
of multiple small Messages into larger packets (Nagle's
algorithm), to signal a preference for lower-latency, higher-loss
treatment, and so on.
Paragraph (version A):
Delay and delay variation should be optimized at the expense of
bandwidth efficiency.
Paragraph (version B):
Delay and delay variation should be minimized at the expense of
bandwidth efficiency.
Draft: draft-trammell-taps-interface

Commentary: TEXT : informed when an ICMP error message arrives . I think this is OK . but is this intended to be for soft - errors , since hard - errors break the connection ? I think I get this , although some transports obvioulsy " eat " the ICMP packets they receive , and many ICMP messages have no meaning to an app , but some can be important . Tell me more please ... 
 this comes from minset - and so it ’s based on the rfc “ soft error ” text . true , no guarantee that you get it . 
 So , maybe the next rev of text should just say this and it will be fine .
Paragraph (version A):
Notification of ICMP error message arrival: This boolean property
specifies whether an application considers it useful to be
informed when an ICMP error message arrives.  This property
applies to Connections and Connection Groups.  This is not a
strict requirement.  The default is to have this option.
Paragraph (version B):
Notification of ICMP soft error message arrival: This boolean
property specifies whether an application considers it useful to
be informed when an ICMP error message arrives that does not force
termination of a connection.  This property applies to Connections
and Connection Groups.  Received ICMP errors will be available as
SoftErrors.  Note that even if a protocol supporting this property
is selected, not all ICMP errors will necessarily be delivered, so
applications cannot rely on receiving them.  This is not a strict
requirement.  The default is not to have this option.
Paragraph (version B):
A SoftError can inform the application about the receipt of an ICMP
error message that does not force termination of the connection, if
the underlying protocol stack supports access to soft errors;
however, even if the underlying stack supports it, there is no
guarantee that a soft error will be signaled.
Draft: draft-trammell-taps-interface

Commentary: lgtmIndeed , much nicer !
Paragraph (version A):
Messages may be arbitrarily large; however, there may be system and
Protocol Stack dependent limits on the size of a data object which
can be transmitted atomically.  For that reason, the Message object
passed to the Send action may also be a partial Message, either
representing the whole data object and information about the range of
bytes to send from it, or an object referring back to the larger
whole Message.  The details of partial Message sending are
implementation-dependent.
Paragraph (version B):
Some transport protocols can deliver arbitrarily sized Messages, but
other protocols constrain the maximum Message size.  Applications can
query the protocol property Maximum Message Size on Send to determine
the maximum size.
Paragraph (version B):
There may also be system and Protocol Stack dependent limits on the
size of a Message which can be transmitted atomically.  For that
reason, the Message object passed to the Send action may also be a
partial Message, either representing the whole data object and
information about the range of bytes to send from it, or an object
referring back to the larger whole Message.  The details of partial
Message sending are implementation-dependent.
Draft: draft-trammell-taps-interface

Commentary: This addresses 
 Review the use of notation in the API doc before final submission and unify it stylistically .
Paragraph (version A):
Once a Connection is established, data can be sent on it in the form
of Messages.  The interface supports the preservation of message
boundaries both via explicit protocol stack support, and via
application support through a deframing callback which finds message
boundaries in a stream.  Messages are received asynchronously through
a callback registered by the application.  Error and other
notifications also happen asynchronously on the Connection.
Paragraph (version B):
Once a Connection is established, data can be sent on it in the form
of Messages.  The interface supports the preservation of message
boundaries both via explicit Protocol Stack support, and via
application support through a deframing callback which finds message
boundaries in a stream.  Messages are received asynchronously through
a callback registered by the application.  Errors and other
notifications also happen asynchronously on the Connection.
Paragraph (version A):
In order to specify Specific Protocol Properties, Transport System
implementations may offer applications to attach a set of options to
the Preconnection object, associated with a specific protocol.  For
example, an application could specify a set of TCP Options to use if
and only if TCP is selected by the system.  Such properties must not
be assumed to apply across different protocols.  Attempts to set
specific protocol properties on a protocol stack not containing that
specific protocol are simply ignored, and do not raise an error..
Paragraph (version B):
In order to specify Specific Protocol Properties, Transport System
implementations may offer applications to attach a set of options to
the Preconnection Object, associated with a specific protocol.  For
example, an application could specify a set of TCP Options to use if
and only if TCP is selected by the system.  Such properties must not
be assumed to apply across different protocols.  Attempts to set
specific protocol properties on a Protocol Stack not containing that
specific protocol are simply ignored, and do not raise an error.
Draft: draft-trammell-taps-interface

Commentary: For the Constant Rate capacity profile , should we state that this implies that the connection will fail if there is insufficient capacity ? ( i.e. , you 're requesting a circuit breaker rather than congestion control ) 
 may fail instead of will fail , but yeah , this seems sensible . 
 lgtm
Paragraph (version A):
The application expects to send/receive data at a constant rate
after connection establishment.  Delay and delay variation
should be optimized at the expense of bandwidth efficiency.
Paragraph (version B):
The application expects to send/receive data at a constant rate
after connection establishment.  Delay and delay variation
should be optimized at the expense of bandwidth efficiency.
This implies that the Connection may fail if the desired rate
cannot be maintained across the Path.  A transport may
interpret this capacity profile as preferring a circuit breaker
RFC8084 to a rate adaptive congestion controller.
Draft: draft-trammell-taps-interface

Commentary: as suggested in the discussion on
Paragraph (version A):
Receive takes a single object, a ReceiveHandler which can handle the
Received event and the ReceiveError error.  Each call to Receive will
result in at most one Received event being sent to the handler,
though implementations may provide convenience functions to indicate
readiness to receive a larger but finite number of Messages with a
single call.  This allows an application to provide backpressure to
the transport stack when it is temporarily not ready to receive
messages.
Paragraph (version B):
Receive takes a ReceiveHandler, which can handle the Received event
and the ReceiveError error.  Each call to Receive will result in at
most one Received event being sent to the handler, though
implementations may provide convenience functions to indicate
readiness to receive a larger but finite number of Messages with a
single call.  This allows an application to provide backpressure to
the transport stack when it is temporarily not ready to receive
messages.
Paragraph (version B):
Receive also takes an optional maxLength argument, the maximum size
(in bytes of data) Message the application is currently prepared to
receive.  The default value for maxLength is infinite.  If an
incoming Message is larger than the minimum of this size and the
maximum non-partial Message size on receive for the Connection's
Protocol Stack, it will be received as a partial Message.  Note that
maxLength does not guarantee that the application will receive that
many bytes if they are available; the interface may return partial
Messages smaller than maxLength according to implementation
constraints.
Draft: draft-trammell-taps-interface

Commentary: What makes these errors " special " ? It seems a strange term to use , and the meaning is unclear . 
 I did n't write this , but I think it was an effort to lump together , from minset , two quite different types of errors : 1 ) notification of excessive retransmissions ; 2 ) notification of icmp error message arrival . Any suggestions for a common term ? 
 If it 's just those two types of errors , we can probably just list them ... 
 is what I did in minset :) 
 so the suggestion is to split these out into two protocol selection properties ? 
 yes , I think so 
 all right then , see 
 lgtm
Paragraph (version A):
Notification of special errors (excessive retransmissions, ICMP
error message arrival): This boolean property specifies whether an
application considers it useful to be informed in case sent data
was retransmitted more often than a certain threshold, or when an
ICMP error message arrives.  This property applies to Connections
and Connection Groups.  This is not a strict requirement.  The
default is to have this option.
Paragraph (version B):
Notification of excessive retransmissions: This boolean property
specifies whether an application considers it useful to be
informed in case sent data was retransmitted more often than a
certain threshold.  This property applies to Connections and
Connection Groups.  This is not a strict requirement.  The default
is to have this option.
Paragraph (version B):
Notification of ICMP error message arrival: This boolean property
specifies whether an application considers it useful to be
informed when an ICMP error message arrives.  This property
applies to Connections and Connection Groups.  This is not a
strict requirement.  The default is to have this option.
Draft: draft-trammell-taps-interface

Commentary: The API document says : I 'm not sure I follow this . The text does n't seem to match the option name : it is n't saying use connection groups efficiently or not , it 's specifying whether connection groups can be used at all . It 's also not clear why prioritisation is given as an example . Would it be clearer written something more like the following ? 
 yep . Although you still have to explicitly entangle connections by cloning them if you want them to be guaranteed to be within a connection group . 
 makes me question why we need this parameter ? 
 To explicitly prefer multistreaming protocols during selection , because you wrote your app to clone connections instead of cloning preconnections . 
 ( see )
Paragraph (version A):
Efficient use of Connection Groups: This boolean property
specifies whether an application considers it useful to create
Connection Groups, e.g. to explicitly prioritize between
Connections within a Connection Group.  This property will tend to
select multistreaming transport protocols, which can multiplex
Connections into a Connection Group over a single flow.  This is
not a strict requirement.  The default is to not have this option.
Paragraph (version B):
Multiplex connections: This boolean property specifies that the
application would prefer multiple Connections between the same
endpoints within a Connection Group to be multiplexed onto a
single underlying transport connection where possible, for reasons
of efficiency.  This is not a strict requirement.  The default is
to not have this option.
Paragraph (version A):
Establishing a Connection from a cloned Preconnection will not cause
Connections for other entangled Preconnections to be established;
each such Connection must be established separately.  Changes to the
parameters of a Preconnection entangled with a Preconnection from
which a Connection has already been established will fail.  Calling
Clone on a Preconnection may be taken by the system an implicit sign
that protocol stacks supporting efficient connection group usage are
preferred by the application.
Paragraph (version B):
Establishing a Connection from a cloned Preconnection will not cause
Connections for other entangled Preconnections to be established;
each such Connection must be established separately.  Changes to the
parameters of a Preconnection entangled with a Preconnection from
which a Connection has already been established will fail.  Calling
Clone on a Preconnection may be taken by the system an implicit
signal that protocol stacks supporting multiplexed connections for
efficient connection grouping are preferred by the application.
Draft: draft-trammell-taps-interface

Commentary: There are still a few s and similar scattered throughout the document . Find them and fix them , or move them to post - London issues .
Paragraph (version A):
In the following sections, we describe the details of application
interaction with Objects through Actions and Events in each phase of
a connection, following the phases described in TAPS-ARCH.
Paragraph (version B):
The Transport Services Interface is the basic common abstract
application programming interface to the Transport Services
Architecture defined in TAPS-ARCH.  An application primarily
interacts with this interface through two objects, Preconnections and
Connections.  A Preconnection represents a set of parameters and
constraints on the selection and configuration of paths and protocols
to establish a connection with a remote endpoint.  A Connection
represents a transport protocol stack on which data can be sent to
and received from a remote endpoint.  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):
Once a Connection is established, data can be sent on it in the form
of Messages.  The interface supports the preservation of message
boundaries both via explicit protocol stack support, and via
application support through a deframing callback which finds message
boundaries in a stream.  Messages are received asynchronously through
a callback registered by the application.  Error and other
notifications also happen asynchronously on the Connection.
Paragraph (version B):
In the following sections, we describe the details of application
interaction with Objects through Actions and Events in each phase of
a connection, following the phases described in TAPS-ARCH.  An
example interface sketch in Go is shown in appendix-api-sketch.
Draft: draft-trammell-taps-interface

Commentary: note this one has an edit about Receive callbacks that only makes sense once lands ...
Paragraph (version A):
How these abstract concepts map into concrete implementations of this
API in a given language on a given platform is largely dependent on
the features of the language and the platform.  Actions could be
implemented as functions or method calls, for instance, and Events
could be implemented via callback passing or other asynchronous
calling conventions.
Paragraph (version B):
How these abstract concepts map into concrete implementations of this
API in a given language on a given platform is largely dependent on
the features of the language and the platform.  Actions could be
implemented as functions or method calls, for instance, and Events
could be implemented via callback passing or other asynchronous
calling conventions.  The method for registering callbacks and
handlers is left as an implementation detail, with the caveat that
the interface for receiving Messages must require the application to
invoke the Connection.Receive() action once per Message to be
received (see receiving).
Paragraph (version B):
This specification treats events and errors similarly, as errors,
just as any other events, may occur asynchronously in network
applications.  However, it is recommended that implementations of
this interface also return errors immediately, according to the error
handling idioms of the implementation platform, for errors which can
be immediately detected, such as inconsistency in transport
parameters.