doc/modules/: Make docs use more consistent sentence structure

Author: daurnimator

doc/interfaces/connection.md

@@ -18,7 +18,7 @@ The HTTP version number of the connection as a number.
 
 ### `connection:connect(timeout)` <!-- --> {#connection:connect}
 
-Completes the connection to the remote server using the address specified, HTTP version and any options specified in the `connection.new` constructor. The `connect` function will yield until the connection attempt finishes (success or failure) or until `timeout` is exceeded. Connecting may include DNS lookups, TLS negotiation and HTTP2 settings exchange. Returns `true` on success. On failure returns `nil` and an error message.
+Completes the connection to the remote server using the address specified, HTTP version and any options specified in the `connection.new` constructor. The `connect` function will yield until the connection attempt finishes (success or failure) or until `timeout` is exceeded. Connecting may include DNS lookups, TLS negotiation and HTTP2 settings exchange. Returns `true` on success. On error, returns `nil`, an error message and an error number.
 
 
 ### `connection:checktls()` <!-- --> {#connection:checktls}
@@ -28,12 +28,12 @@ Checks the socket for a valid Transport Layer Security connection. Returns the l
 
 ### `connection:localname()` <!-- --> {#connection:localname}
 
-Returns the connection information for the local socket. Returns address family, IP address and port for an external socket. For Unix domain sockets, the function returns `AF_UNIX` and the path. If the connection object is not connected, returns `AF_UNSPEC` (0). On error, returns `nil` an error message and an error number.
+Returns the connection information for the local socket. Returns address family, IP address and port for an external socket. For Unix domain sockets, the function returns `AF_UNIX` and the path. If the connection object is not connected, returns `AF_UNSPEC` (0). On error, returns `nil`, an error message and an error number.
 
 
 ### `connection:peername()` <!-- --> {#connection:peername}
 
-Returns the connection information for the socket *peer* (as in, the next hop). Returns address family, IP address and port for an external socket. For unix sockets, the function returns `AF_UNIX` and the path. If the connection object is not connected, returns `AF_UNSPEC` (0). On error, returns `nil` an error message and an error number.
+Returns the connection information for the socket *peer* (as in, the next hop). Returns address family, IP address and port for an external socket. For unix sockets, the function returns `AF_UNIX` and the path. If the connection object is not connected, returns `AF_UNSPEC` (0). On error, returns `nil`, an error message and an error number.
 
 *Note: If the client is using a proxy, the values returned `:peername()` point to the proxy, not the remote server.*
 
@@ -55,7 +55,7 @@ Closes a connection and releases operating systems resources. Note that `:close(
 
 ### `connection:new_stream()` <!-- --> {#connection:new_stream}
 
-Creates a new [*stream*](#stream) on the connection. Use `:new_stream()` to initiate a new http request. In HTTP 1, a new stream can be used for request/response exchanges. In HTTP 2 a new stream can be used for request/response exchanges, organising stream priorities or to initiate a push promise.
+Creates and returns a new [*stream*](#stream) on the connection.
 
 
 ### `connection:get_next_incoming_stream(timeout)` <!-- --> {#connection:get_next_incoming_stream}

doc/interfaces/stream.md

@@ -1,5 +1,7 @@
 ## stream
 
+An HTTP *stream* is an abstraction of a request/response within a HTTP connection. Within a stream there may be a number of "header" blocks as well as data known as the "body".
+
 All stream types expose the following fields and functions:
 
 ### `stream.connection` <!-- --> {#stream.connection}

doc/modules/http.h1_connection.md

@@ -1,10 +1,10 @@
 ## http.h1_connection
 
-The h1_connection module adheres to the [*connection*](#connection) interface and provides HTTP 1 and 1.1 specific operations.
+The *h1_connection* module adheres to the [*connection*](#connection) interface and provides HTTP 1 and 1.1 specific operations.
 
 ### `new(socket, conn_type, version)` <!-- --> {#connection.new}
 
-Constructor for a new connection. Takes a socket instance, a connection type string and a numeric HTTP version number. Valid values for the connection type are `"client"` and `"server"`. Valid values for the version number are `1` and `1.1`. On success returns the newly initialized connection object in a non-connected state. On failure returns `nil`, an error message and an error number.
+Constructor for a new connection. Takes a cqueues socket object, a [connection type string](#connection.type) and a numeric HTTP version number. Valid values for the connection type are `"client"` and `"server"`. Valid values for the version number are `1` and `1.1`. Returns the newly initialized connection object.
 
 
 ### `h1_connection.version` <!-- --> {#http.h1_connection.version}
@@ -54,6 +54,8 @@ See [`connection:close()`](#connection:close)
 
 ### `h1_connection:new_stream()` <!-- --> {#http.h1_connection:new_stream}
 
+In HTTP 1, only a client may initiate new streams with this function.
+
 See [`connection:new_stream()`](#connection:new_stream) for more information.
 
 

doc/modules/http.h1_stream.md

@@ -1,6 +1,6 @@
 ## http.h1_stream
 
-An h1_stream represents an HTTP 1.0 or 1.1 request/response. The module follows the [*stream*](#stream) interface as well as HTTP 1.x specific functions.
+The *h1_stream* module adheres to the [*stream*](#stream) interface and provides HTTP 1.x specific operations.
 
 The gzip transfer encoding is supported transparently.
 

doc/modules/http.h2_connection.md

@@ -1,14 +1,16 @@
 ## http.h2_connection
 
-An HTTP 2 connection can have multiple streams actively transmitting data at once,
+The *h2_connection* module adheres to the [*connection*](#connection) interface and provides HTTP 2 specific operations. An HTTP 2 connection can have multiple streams actively transmitting data at once,
 hence an *http.h2_connection* acts much like a scheduler.
 
 ### `new(socket, conn_type, settings)` <!-- --> {#http.h2_connection.new}
 
+Constructor for a new connection. Takes a cqueues socket object, a [connection type string](#connection.type) and an optional table of HTTP 2 settings. Returns the newly initialized connection object in a non-connected state.
+
 
 ### `h2_connection.version` <!-- --> {#http.h2_connection.version}
 
-Contains the value of the HTTP 2 version number for the connection. Currently will hold the value of `2`.
+Contains the HTTP connection version. Currently this will always be `2`.
 
 See [`connection.version`](#connection.version)
 
@@ -68,8 +70,8 @@ See [`connection:close()`](#connection:close)
 
 ### `h2_connection:new_stream(id)` <!-- --> {#http.h2_connection:new_stream}
 
-`id` (optional) is the stream id to assign the new stream. For client initiated streams, this will be the next free odd numbered stream.
-For server initiated streams, this will be the next free even numbered stream.
+Create and return a new [*h2_stream*](#http.h2_stream).
+`id` (optional) is the stream id to assign the new stream, if not specified for client initiated streams this will be the next free odd numbered stream, for server initiated streams this will be the next free even numbered stream.
 
 See [`connection:new_stream()`](#connection:new_stream) for more information.
 

doc/modules/http.h2_stream.md

@@ -105,6 +105,10 @@ See [`stream:shutdown()`](#stream:shutdown)
 
 ### `h2_stream:write_http2_frame(typ, flags, payload, timeout)` <!-- --> {#http.h2_stream:write_http2_frame}
 
+Writes a frame with `h2_stream`'s stream id.
+
+See [`h2_connection:write_http2_frame(typ, flags, streamid, payload, timeout)`](#http.h2_connection:write_http2_frame)
+
 
 ### `h2_stream:write_data_frame(payload, end_stream, padded, timeout)` <!-- --> {#http.h2_stream:write_data_frame}
 

doc/modules/http.server.md

@@ -53,7 +53,7 @@ Initializes the server socket and if required, resolves DNS. `server:listen()` i
 
 ### `server:localname()` <!-- --> {#http.server:localname}
 
-Returns the connection information for the local socket. Returns address family, IP address and port for an external socket. For Unix domain sockets, the function returns AF_UNIX and the path. If the connection object is not connected, returns AF_UNSPEC (0). On error, returns `nil` an error message and an error number.
+Returns the connection information for the local socket. Returns address family, IP address and port for an external socket. For Unix domain sockets, the function returns AF_UNIX and the path. If the connection object is not connected, returns AF_UNSPEC (0). On error, returns `nil`, an error message and an error number.
 
 
 ### `server:pause()` <!-- --> {#http.server:pause}
@@ -99,7 +99,7 @@ Returns `true` if the master socket and all client connection have been closed,
 
 ### `server:step(timeout)` <!-- --> {#http.server:step}
 
-Step once through server's main loop: any waiting clients will be `accept()`-ed, any pending streams will start getting processed, and each `onstream` handler will get be run at most once. This method will block for *up to* `timeout` seconds. Returns `nil`, an error and an error message on failure.
+Step once through server's main loop: any waiting clients will be `accept()`-ed, any pending streams will start getting processed, and each `onstream` handler will get be run at most once. This method will block for *up to* `timeout` seconds. On error, returns `nil`, an error message and an error number.
 
 This can be used for integration with external main loops.
 

doc/modules/http.socks.md

@@ -33,9 +33,7 @@ Add username + password authorisation to the set of allowed authorisation method
 
 Complete the SOCKS connection.
 
-Negotiates a socks connection. `host` is a required string passed to the SOCKS server as the host address. The address will be resolved locally if [`.needs_resolve`](#http.socks.needs_resolve) is `true`. `port` is a required number to pass to the SOCKS server as the connection port.
-
-On error, returns `nil` an error message and an error number.
+Negotiates a socks connection. `host` is a required string passed to the SOCKS server as the host address. The address will be resolved locally if [`.needs_resolve`](#http.socks.needs_resolve) is `true`. `port` is a required number to pass to the SOCKS server as the connection port. On error, returns `nil`, an error message and an error number.
 
 
 ### `socks:close()` <!-- --> {#http.socks:close}