Documentation Feedback Changes (#46)

README.md

@@ -20,7 +20,7 @@ QUIC has many benefits when compared to existing TLS over TCP scenarios:
   * Survives a change in the clients IP address or port.
   * Easily extendable for new features (such as unreliable delivery).
 
-> **Important** Several QUIC protocol features are not fully implemented:
+> **Important** Several QUIC protocol features are not yet fully implemented:
 >
 >  * 0-RTT with Schannel and OpenSSL
 >  * NAT Rebinding
@@ -30,8 +30,9 @@ QUIC has many benefits when compared to existing TLS over TCP scenarios:
 
 ## Library Features
 
+  * Cross-platform support.
   * Optimized for maximal throughput and minimal latency.
-  * Asychronous IO.
+  * Asynchronous IO.
   * Receive side scaling (RSS).
   * UDP send and receive coalescing support.
 

docs/API.md

@@ -33,9 +33,9 @@ The API supports both server and client applications. All functionality is expos
 
 [**Registration**](#registration) – Manages the execution context for all child objects. An app may open multiple registrations but ideally should only open one.
 
-[**Security Configuration**](#security-configuration) – Abstracts the configuration for the TLS layer. This primarily consists of a certificate that is used for authentication. The app may create as many of these as necessary.
+[**Security Configuration**](#security-configuration) – Abstracts the configuration for the TLS component. This primarily consists of a certificate that is used for authentication. The app may create as many of these as necessary.
 
-[**Session**](#session) – Abstracts several different session-layer concepts: TLS Session Resumption, Application Protocol Layer Negotiation (ALPN) and platform specifics (such as Server Silo and Network Compartment ID on Windows). The app may create as many of these as necessary.
+[**Session**](#session) – Abstracts several different session-layer concepts: TLS Session Resumption, Application Layer Protocol Negotiation (ALPN) and platform specifics (such as Server Silo and Network Compartment ID on Windows). The app may create as many of these as necessary.
 
 [**Listener**](#listener) – Server side only, this object provides the interface for an app to accept incoming connections from clients. Once the connection has been accepted, it is independent of the listener. The app may create as many of these as necessary.
 
@@ -101,23 +101,23 @@ A session is created by calling [SessionOpen](v1/SessionOpen.md) and deleted by
 
 ## Listener
 
-To create a QUIC server, an app must create a listener via [ListenerOpen](v1/ListenerOpen.md). This will return a new listener handle that is ready to start accepting incoming connections. Then, the app must call [ListenerStart](v1/ListenerStart.md) to get callbacks for new incoming connections. [ListenerStart](v1/ListenerStart.md) takes the network address the app wants to listener on.
+To create a QUIC server, a server must create a listener via [ListenerOpen](v1/ListenerOpen.md). This will return a new listener handle that is ready to start accepting incoming connections. Then, the server must call [ListenerStart](v1/ListenerStart.md) to get callbacks for new incoming connections. [ListenerStart](v1/ListenerStart.md) takes the network address the server wants to listener on.
 
-When a new connection is started by a client, the app will get a callback allowing it to accept the connection. This happens via the `QUIC_LISTENER_EVENT_NEW_CONNECTION` callback event, which contains all the currently known information in the `QUIC_NEW_CONNECTION_INFO` struct. The app is required to do one of three things in response to this event:
+When a new connection is started by a client, the server will get a callback allowing it to accept the connection. This happens via the `QUIC_LISTENER_EVENT_NEW_CONNECTION` callback event, which contains all the currently known information in the `QUIC_NEW_CONNECTION_INFO` struct. The server is required to do one of three things in response to this event:
 
 1. Return a failure status, indicating it didn’t accept the new connection.
 2. Return `QUIC_STATUS_SUCCESS` and set the SecConfig output parameter in the event.
 3. Return `QUIC_STATUS_PENDING`, which allows the SecConfig to be set later, via a call to SetParam with the `QUIC_PARAM_CONN_SEC_CONFIG` option.
 
-If both 2 and 3 above, the app now has ownership of the connection object. It **must** set the callback handler via [SetCallbackHandler](v1/SetCallbackHandler.md) before the callback returns. Additionally, it must call [ConnectionClose](v1/ConnectionClose.md) on the connection to clean it up when it’s done with the connection. Also, in case 2, if the app does not set the SecConfig, it is treated as case 1.
+If either 2 or 3 above, the server now has ownership of the connection object. It **must** set the callback handler via [SetCallbackHandler](v1/SetCallbackHandler.md) before the callback returns. Additionally, when it’s done with the connection, the app must call [ConnectionClose](v1/ConnectionClose.md) on the connection to clean it up. Also, in case 2, if the server does not set the SecConfig, it is treated as case 1.
 
-When the app wishes to stop accepting new connections and stop further callbacks to the registered handler, it can call [ListenerStop](v1/ListenerStop.md). This call will block while any existing callbacks complete, and when it returns no future callbacks will occur. Therefore, the app ***must not** call this on any other library callbacks. The app may call [ListenerStart](v1/ListenerStart.md) again on the listener to start listening for incoming connections again.
+When the server wishes to stop accepting new connections and stop further callbacks to the registered handler, it can call [ListenerStop](v1/ListenerStop.md). This call will block while any existing callbacks complete, and when it returns no future callbacks will occur. Therefore, the server **must not** call this on any other library callbacks. The server may call [ListenerStart](v1/ListenerStart.md) again on the listener to start listening for incoming connections again.
 
-To clean up the listener object, the app calls [ListenerClose](v1/ListenerClose.md). If the listener was not previously stopped, this function implicitly calls [ListenerStop](v1/ListenerStop.md), so all the same restrictions to that call apply.
+To clean up the listener object, the server calls [ListenerClose](v1/ListenerClose.md). If the listener was not previously stopped, this function implicitly calls [ListenerStop](v1/ListenerStop.md), so all the same restrictions to that call apply.
 
 ## Connection
 
-A connection handle represents a single QUIC connection and is generally the same thing on both client and server side. The main difference between client and server is just how the handle gets initially created. On client it is created explicitly by the app via a call to [ConnectionOpen](v1/ConnectionOpen.md). On server it is created by the listener and delivered to the app via a callback to the registered `QUIC_LISTENER_CALLBACK_HANDLER`. Just like all objects in MsQuic, the connection requires the app to be registered for event callbacks always. After the client creates the new connection, it starts the process of connecting to a remote server by calling [ConnectionStart](v1/ConnectionStart.md). If the connection attempt succeeds, the connection event handler will be invoked for a `QUIC_CONNECTION_EVENT_CONNECTED` event; otherwise a `QUIC_CONNECTION_EVENT_CLOSED` event will be received.
+A connection handle represents a single QUIC connection and is generally the same thing on both client and server side. The main difference between client and server is just how the handle gets initially created. On client it is created explicitly by the app via a call to [ConnectionOpen](v1/ConnectionOpen.md). On server it is created by the listener and delivered to the app via a callback to the registered `QUIC_LISTENER_CALLBACK_HANDLER`. Just like all objects in MsQuic, the connection requires the app to always be registered for event callbacks. After the client creates the new connection, it starts the process of connecting to a remote server by calling [ConnectionStart](v1/ConnectionStart.md). If the connection attempt succeeds, the connection event handler will be invoked for a `QUIC_CONNECTION_EVENT_CONNECTED` event; otherwise a `QUIC_CONNECTION_EVENT_CLOSED` event will be received.
 
 Once the app has a connection (either client or server) it can start opening streams and receiving events for remotely opened streams. Remotely opened streams are indicated to the callback handler via a `QUIC_CONNECTION_EVENT_NEW_STREAM` event. The app is required to immediately call [SetCallbackHandler](v1/SetCallbackHandler.md) to register a callback handler for the new stream. See [Stream](#stream) usage for more details on how stream are used.
 
@@ -125,8 +125,8 @@ When the app is done with the connection, it can then call [ConnectionShutdown](
 
 ## Stream
 
-Streams are the primary means of exchanging app data over a connection. Streams can be bidirectional and unidirectional. They can also be initiated/opened by either endpoint (Client or server). Each endpoint dicates exactly how many streams of each type (unidirectional or bidirectional) their peer can open at a given time. Finally, they can be shutdown by either endpoint, in either direction.
+Streams are the primary means of exchanging app data over a connection. Streams can be bidirectional or unidirectional. They can also be initiated/opened by either endpoint (Client or server). Each endpoint dictates exactly how many streams of each type (unidirectional or bidirectional) their peer can open at a given time. Finally, they can be shutdown by either endpoint, in either direction.
 
-A stream handle represents a single QUIC stream. It can be locally created by a call to [StreamOpen](v1/StreamOpen.md) or remotely created and then indicated to the app via the connection's callback handler via a `QUIC_CONNECTION_EVENT_PEER_STREAM_STARTED` event. Locally created streams must be started (via [StreamStart](v1/StreamStart.md)) before they can practically be used. Remote streams are already started when indicated to the app.
+A stream handle represents a single QUIC stream. It can be locally created by a call to [StreamOpen](v1/StreamOpen.md) or remotely created and then indicated to the app via the connection's callback handler via a `QUIC_CONNECTION_EVENT_PEER_STREAM_STARTED` event. Locally created streams must be started (via [StreamStart](v1/StreamStart.md)) before they can send or receive data. Remote streams are already started when indicated to the app.
 
 Once the stream handle is available and started, the app can start receiving events on its callback handler (such as `QUIC_STREAM_EVENT_RECV`) and start sending on the stream (via [StreamSend](v1/StreamSend.md)). For more details see [Using Streams](Streams.md).