Improve documentation and transport semantics

net/http/client.ha

@@ -10,9 +10,16 @@ export type client = struct {
 	default_transport: transport,
 };
 
-// Creates a new HTTP [[client]] with the provided User-Agent string, which is
+// Creates a new HTTP [[client]] with the provided User-Agent string.
-// borrowed from the caller. Pass the return value to [[client_finish]] to free
+//
-// resourfces associated with the HTTP client after use.
+// The HTTP client implements a number of sane defaults, which may be tuned. The
+// set of default headers is configured with [[client_default_header]], and the
+// default transport behavior with [[client_default_transport]].
+//
+// TODO: Implement and document the connection pool
+//
+// The caller must pass the client object to [[client_finish]] to free resources
+// associated with this client after use.
 export fn newclient(ua: str) client = {
 	let client = client { ... };
 	header_add(&client, "User-Agent", ua);

net/http/request.ha

@@ -2,6 +2,11 @@ use io;
 use net::uri;
 
 // Stores state related to an HTTP request.
+//
+// For a request to be processable by an HTTP [[client]], i.e. via [[do]], the
+// method and target must be filled in appropriately. The target must include at
+// least a host, port, and scheme. The default values for other fields are
+// suitable if appropriate for the request you wish to perform.
 export type request = struct {
 	// HTTP request method, e.g. GET
 	method: str,
@@ -18,7 +23,7 @@ export type request = struct {
 	// Transport configuration, or null to use the [[client]] default.
 	transport: nullable *transport,
 
-	// I/O reader for the request body.
+	// I/O reader for the request body, or void if there is no body.
 	body: (io::handle | void),
 };
 

net/http/transport.ha

@@ -6,46 +6,50 @@ use strconv;
 use strings;
 use types;
 
-// Configures the transport mode.
+// Configures the Transport-Encoding behavior.
 //
-// For clients, if set to "none", no transport decoding is performed on the
+// If set to "none", no transport decoding or encoding is performed on the
-// response body, and the user must read the Transport-Encoding header and
+// message body, irrespective of the value of the Transport-Encoding header. The
-// decode it themselves. If set to "auto", [[response]].body will be decoded
+// user must perform any required encoding or decoding themselves in this mode.
-// according to the response's Transport-Encoding header. Most users will want
+// If set to "auto", the implementation will examine the Transport-Encoding
-// this to be set to "auto".
+// header and encode the message body appropriately.
 //
-// For servers, if set to "auto", net::http will examine the Transport-Encoding
+// Most users will want this to be set to "auto".
-// header and apply the appropriate transport encoding. If set to "none", the
+//
-// response body will be sent directly to the client with no further processing.
+// TODO: Document server behavior
 export type transport_mode = enum {
 	AUTO = 0,
 	NONE,
 };
 
-// Configures the content mode.
+// Configures the Content-Encoding behavior.
 //
-// For clients, if set to "none", no content decoding is performed on the
+// If set to "none", no transport decoding or encoding is performed on the
-// response body, and the user must read the Content-Encoding header and decode
+// message body, irrespective of the value of the Content-Encoding header. The
-// it themselves. If set to "auto", [[response]].body will be decoded according
+// user must perform any required encoding or decoding themselves in this mode.
-// to the response's Content-Encoding header. Most users will want this to be
+// If set to "auto", the implementation will examine the Content-Encoding header
-// set to "auto".
+// and encode the message body appropriately.
 //
-// For servers, if set to "auto", net::http will examine the Content-Encoding
+// Most users will want this to be set to "auto".
-// header and apply the appropriate content encoding. If set to "none", the
+//
-// response body will be sent directly to the client with no further processing.
+// TODO: Document server behavior
 export type content_mode = enum {
 	AUTO = 0,
 	NONE,
 };
 
 // Describes an HTTP [[client]]'s transport configuration for a given request.
+//
+// The default value of this type sets all parameters to "auto".
 export type transport = struct {
 	// Desired Transport-Encoding configuration, see [[transport_mode]] for
 	// details.
-	transport: transport_mode,
+	request_transport: transport_mode,
+	response_transport: transport_mode,
 	// Desired Content-Encoding configuration, see [[content_mode]] for
 	// details.
-	content: content_mode,
+	request_content: content_mode,
+	response_content: content_mode,
 };
 
 fn new_reader(