Big improvements to doc comments

wit/handler.wit

@@ -1,43 +1,39 @@
-// The `wasi:http/incoming-handler` interface is meant to be exported by
-// components and called by the host in response to a new incoming HTTP
-// response.
-//
-//   NOTE: in Preview3, this interface will be merged with
-//   `wasi:http/outgoing-handler` into a single `wasi:http/handler` interface
-//   that takes a `request` parameter and returns a `response` result.
-//
+/// This interface defines a handler of incoming HTTP Requests. It should
+/// be exported by components which can respond to HTTP Requests.
 interface incoming-handler {
   use types.{incoming-request, response-outparam};
 
-  // The `handle` function takes an outparam instead of returning its response
-  // so that the component may stream its response while streaming any other
-  // request or response bodies. The callee MUST write a response to the
-  // `response-outparam` and then finish the response before returning. The `handle`
-  // function is allowed to continue execution after finishing the response's
-  // output stream. While this post-response execution is taken off the
-  // critical path, since there is no return value, there is no way to report
-  // its success or failure.
+  /// This function is invoked with an incoming HTTP Request, and a resource
+  /// `response-outparam` which provides the capability to reply with an HTTP
+  /// Response. The response is sent by calling the `response-outparam.set`
+  /// method, which allows execution to continue after the response has been
+  /// sent. This enables both streaming to the response body, and performing other
+  /// work.
+  ///
+  /// The implementor of this function must write a response to the
+  /// `response-outparam` before returning, or else the caller will respond
+  /// with an error on its behalf.
   handle: func(
     request: incoming-request,
     response-out: response-outparam
   );
 }
 
-// The `wasi:http/outgoing-handler` interface is meant to be imported by
-// components and implemented by the host.
-//
-//   NOTE: in Preview3, this interface will be merged with
-//   `wasi:http/outgoing-handler` into a single `wasi:http/handler` interface
-//   that takes a `request` parameter and returns a `response` result.
-//
+/// This interface defines a handler of outgoing HTTP Requests. It should be
+/// imported by components which wish to make HTTP Requests.
 interface outgoing-handler {
   use types.{outgoing-request, request-options, future-incoming-response, error};
 
-  // The parameter and result types of the `handle` function allow the caller
-  // to concurrently stream the bodies of the outgoing request and the incoming
-  // response.
-  // Consumes the outgoing-request. Gives an error if the outgoing-request
-  // is invalid or cannot be satisfied by this handler.
+  /// This function is invoked with an outgoing HTTP Request, and it returns
+  /// a resource `future-incoming-response` which represents an HTTP Response
+  /// which may arrive in the future.
+  ///
+  /// The `options` argument accepts optional parameters for the HTTP
+  /// protocol's transport layer.
+  ///
+  /// This function may return an error if the `outgoing-request` is invalid
+  /// or not allowed to be made. Otherwise, protocol errors are reported
+  /// through the `future-incoming-response`.
   handle: func(
     request: outgoing-request,
     options: option<request-options>

wit/proxy.wit

@@ -1,34 +1,34 @@
 package wasi:http;
 
-// The `wasi:http/proxy` world captures a widely-implementable intersection of
-// hosts that includes HTTP forward and reverse proxies. Components targeting
-// this world may concurrently stream in and out any number of incoming and
-// outgoing HTTP requests.
+/// The `wasi:http/proxy` world captures a widely-implementable intersection of
+/// hosts that includes HTTP forward and reverse proxies. Components targeting
+/// this world may concurrently stream in and out any number of incoming and
+/// outgoing HTTP requests.
 world proxy {
-  // HTTP proxies have access to time and randomness.
+  /// HTTP proxies have access to time and randomness.
   import wasi:clocks/wall-clock;
   import wasi:clocks/monotonic-clock;
   import wasi:clocks/timezone;
   import wasi:random/random;
 
-  // Proxies have standard output and error streams which are expected to
-  // terminate in a developer-facing console provided by the host.
+  /// Proxies have standard output and error streams which are expected to
+  /// terminate in a developer-facing console provided by the host.
   import wasi:cli/stdout;
   import wasi:cli/stderr;
 
-  // TODO: this is a temporary workaround until component tooling is able to
-  // gracefully handle the absence of stdin. Hosts must return an eof stream
-  // for this import, which is what wasi-libc + tooling will do automatically
-  // when this import is properly removed.
+  /// TODO: this is a temporary workaround until component tooling is able to
+  /// gracefully handle the absence of stdin. Hosts must return an eof stream
+  /// for this import, which is what wasi-libc + tooling will do automatically
+  /// when this import is properly removed.
   import wasi:cli/stdin;
 
-  // This is the default handler to use when user code simply wants to make an
-  // HTTP request (e.g., via `fetch()`).
+  /// This is the default handler to use when user code simply wants to make an
+  /// HTTP request (e.g., via `fetch()`).
   import outgoing-handler;
 
-  // The host delivers incoming HTTP requests to a component by calling the
-  // `handle` function of this exported interface. A host may arbitrarily reuse
-  // or not reuse component instance when delivering incoming HTTP requests and
-  // thus a component must be able to handle 0..N calls to `handle`.
+  /// The host delivers incoming HTTP requests to a component by calling the
+  /// `handle` function of this exported interface. A host may arbitrarily reuse
+  /// or not reuse component instance when delivering incoming HTTP requests and
+  /// thus a component must be able to handle 0..N calls to `handle`.
   export incoming-handler;
 }