readability edit of section 4.0, complementing my ongoing draft review #1014
Conversation
|
|
||
| ## Structuring Candidates as a Tree | ||
|
|
||
| As noted above, the considereration of multiple candidates in a gathering and racing process can be conceptually structured as a tree; this terminological convention is used throughout this document. | ||
| The considereration of multiple candidates in a gathering and racing process can be conceptually structured as a tree; this terminological convention is used throughout this document. While a tree structure is not the only way in which racing can be implemented, it does ease the illustration of how racing works. |
There was a problem hiding this comment.
| The considereration of multiple candidates in a gathering and racing process can be conceptually structured as a tree; this terminological convention is used throughout this document. While a tree structure is not the only way in which racing can be implemented, it does ease the illustration of how racing works. | |
| The considereration of multiple candidates in a gathering and racing process can be conceptually structured as a tree; this terminological convention is used throughout this document. While a tree structure is not the only way in which racing can be implemented, it is a useful model to use to understand and illustrate connection racing. |
There was a problem hiding this comment.
Doesn't
a useful model to use to
sound slightly odd and redundant?
How about simply saying
it can serve as a useful model to illustrate connection racing
There was a problem hiding this comment.
I don't understand what's slightly odd and redundant about the first version, but I guess both will work. This is for @tfpauly to answer though...
|
|
||
| This document structures the candidates for racing as a tree as terminological convention. While a | ||
| a tree structure is not the only way in which racing can be implemented, it does ease the illustration of how racing works. | ||
| In its most basic form, the connection-establishment process might just involve identifying a single IP address (and port) to which the application wishes to connect, and starting a TCP handshake to establish a stream to that IP address, using the system's current default path (i.e., by using the current default network interface). However, each step may also differ depending on the requirements for the connection: if, instead of a known IP address, the endpoint is identified by a hostname, then there may be a choice between multiple resolved addresses; some protocols may not need any transport handshake to establish communication (such as UDP), while others may require several layers of handshakes, such as TLS over TCP; finally, there may also be multiple paths available (i.e., via additional network interfaces besides the system default); |
There was a problem hiding this comment.
Nit: I think "connection-establishment" should just be "connection establishment".
More broadly, I don't love how this makes the default seem like connecting to an IP address — "if, instead of a known IP address...". The default is going to be higher-level endpoints, and that's a core tenet of the API.
There was a problem hiding this comment.
Agreed. Perhaps replacing the start of that sentence with something like "more commonly, when the endpoint..." will solve this.
There was a problem hiding this comment.
Nit: I think "connection-establishment" should just be "connection establishment".
You're the native speaker ;) I just remember one lesson on formal writing where it was said that there should always be a hyphen whenever you have compound nouns consisting of three words or more. Here, we are talking about a "connection-establishment process" and the hyphen is meant to disambiguate the term from an equally possible "connection establishment-process".
There was a problem hiding this comment.
We could change
if, instead of a known IP address, the endpoint is identified by a hostname, then there may be a choice between multiple resolved addresses;
to simply state that
an endpoint is more commonly identified by a hostname which may resolve into more than one IP address;
There was a problem hiding this comment.
I don't understand the benefit of this suggested change.
There was a problem hiding this comment.
I think Tommy and Anna wanted to emphasize that having a name resolution step is the more common case.
There was a problem hiding this comment.
I see, I'm a little unsure this specific change is really needed... and it doesn't seem to read well, but if it is needed then please consider /which may/that can/ ... and /resolve into/resolve to/
sounds good Co-authored-by: Tommy Pauly <tpauly@apple.com>
|
Many of these changes have been overtaken by other PRs, and I don't think we have consensus on the other changes. As such, I'm closing this PR. |
While reviewing the draft, I found it easy to address some of the issues I saw in section 4.0 in a light edit. I also opened an accompanying issue #1015 containing the relevant review feedback.
I understand this PR as a low-key "take it or leave it" contribution, it wouldn't bother me if it gets summarily rejected
Feedback welcome: is the level of change in this PR too heavy handed or is there interest in similar feedback about other sections of the draft?