Architecture: Editorial comments

[theri]

Having read -05, I have some more comments, mostly editorial.

Opening an issue in case there's anything to discuss. Otherwise I might just do a PR against -arch if that's fine with the authors.

In Section 4.1.1:
"Event Handling (Section 4.1.5) defines the set of properties about which an application can receive notifications during the lifetime of transport objects."
Set of properties? Section 4.1.5 do not refer to specific properties (as in: Transport Properties), but just lists what kinds of events exist. So I suggest changing text in Section 4.1.1 to say something like:
"Event Handling (Section 4.1.5) defines categories of notifications which an application can receive during the lifetime of transport objects."

In Section 4.1.4:
"When receiving Messages, Message Properties can contain per-protocol properties for properties that are sent between the endpoints."
Why is this constrained to properties that are sent between endpoints? Couldn't an implementation also set Message Properties that were not signaled?
Also, what does "per-protocol" mean here?
Also, too many "properties" in this sentence.
I suggest changing this to something like:
"When receiving Messages, Message Properties can contain information about the received message, such as signalled by the other endpoint."

Still Section 4.1.4:
"The status of the Send operation can be delivered back to the sending application in an event"
Can be? I thought this always happens?
The API draft in Section 7.3 says that for each Send(), the application gets exactly one event? So I think here this should be phrased as "is delivered" or even MUST.

Section 4.1.5:
"This section provides the top-level categories of events events that can be delivered to an application."
Top-level categories? Are there more levels of categories? Maybe just say "categories"?
Also, duplicate word: "events events".

Section 4.2.1:
"Protocol Selection: […] choosing one or more sets of protocol options"
I don't think protocol options is the right word. Isn't this about racing protocol stacks? Below we use "protocol options" to mean something else, so here we should just say "choosing between multiple protocol stacks".

"separate DNS resolution stepss" (typo)

Section 6:
"Clients need to ensure that security APIs are used appropriately."
Who or what is a client? An application? Or the transport system itself? I think it's an application. "Clients" is not used elsewhere in the text. So this section should replace "clients" with "applications".

[britram]

All suggestions here are good, please send a PR. I'd rephrase the following:

"When receiving Messages, Message Properties can contain information about the received message, such as signalled by the other endpoint."

to

"When receiving Messages, Message Properties can contain information about the received message, such as metadata generated at the receiver and information signalled by the remote endpoint"

("such as" needs a noun, and I'd like to be more explicit here)