asio: Document public APIs

src/includes/nghttp2/asio_http2.h

@@ -53,10 +53,16 @@ namespace nghttp2 {
 namespace asio_http2 {
 
 struct header_value {
+  // header field value
   std::string value;
+  // true if the header field value is sensitive information, such as
+  // authorization information or short length secret cookies.  If
+  // true, those header fields are not indexed by HPACK (but still
+  // huffman-encoded), which results in lesser compression.
   bool sensitive;
 };
 
+// header fields.  The header field name must be lower-cased.
 using header_map = std::multimap<std::string, header_value>;
 
 const boost::system::error_category &nghttp2_category() noexcept;
@@ -64,9 +70,11 @@ const boost::system::error_category &nghttp2_category() noexcept;
 struct uri_ref {
   std::string scheme;
   std::string host;
-  // percent-decoded form
+  // form after percent-encoding decoded
   std::string path;
+  // original path, percent-encoded
   std::string raw_path;
+  // original query, percent-encoded
   std::string raw_query;
   std::string fragment;
 };
@@ -76,9 +84,21 @@ struct uri_ref {
 typedef std::function<void(const uint8_t *, std::size_t)> data_cb;
 typedef std::function<void(void)> void_cb;
 typedef std::function<void(const boost::system::error_code &ec)> error_cb;
+// Callback function when request and response are finished.  The
+// parameter indicates the cause of closure.
 typedef std::function<void(uint32_t)> close_cb;
 
-// Callback function to generate response body.  TBD
+// Callback function to generate response body.  This function has the
+// same semantics with nghttp2_data_source_read_callback.  Just source
+// and user_data parameters are removed.
+//
+// Basically, write at most |len| bytes to |data| and returns the
+// number of bytes written.  If there is no data left to send, set
+// NGHTTP2_DATA_FLAG_EOF to *data_flags (e.g., *data_flags |=
+// NGHTTP2_DATA_FLAG_EOF).  If there is still data to send but they
+// are not available right now, return NGHTTP2_ERR_DEFERRED.  In case
+// of the error and request/response must be closed, return
+// NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE.
 typedef std::function<
     ssize_t(uint8_t *buf, std::size_t len, uint32_t *data_flags)> read_cb;
 

src/includes/nghttp2/asio_http2_client.h

@@ -37,17 +37,25 @@ class response_impl;
 
 class response {
 public:
+  // Application must not call this directly.
   response();
   ~response();
 
+  // Sets callback which is invoked when chunk of response body is
+  // received.
   void on_data(data_cb cb) const;
 
+  // Returns status code.
   int status_code() const;
 
+  // Returns content-length.  -1 if it is unknown.
   int64_t content_length() const;
 
+  // Returns the response header fields.  The pusedo header fields,
+  // which start with colon (:), are exluced from this list.
   const header_map &header() const;
 
+  // Application must not call this directly.
   response_impl &impl() const;
 
 private:
@@ -65,24 +73,39 @@ class request_impl;
 
 class request {
 public:
+  // Application must not call this directly.
   request();
   ~request();
 
+  // Sets callback which is invoked when response header is received.
   void on_response(response_cb cb) const;
+
+  // Sets callback which is invoked when push request header is
+  // received.
   void on_push(request_cb cb) const;
+
+  // Sets callback which is invoked when this request and response are
+  // finished.  After the invocation of this callback, the application
+  // must not access request and response object.
   void on_close(close_cb cb) const;
 
+  // Cancels this request and response with given error code.
   void cancel(uint32_t error_code = NGHTTP2_INTERNAL_ERROR) const;
 
   // Resumes deferred uploading.
   void resume() const;
 
+  // Returns method (e.g., GET).
   const std::string &method() const;
 
+  // Returns request URI, split into components.
   const uri_ref &uri() const;
 
+  // Returns request header fields.  The pusedo header fields, which
+  // start with colon (:), are exluced from this list.
   const header_map &header() const;
 
+  // Application must not call this directly.
   request_impl &impl() const;
 
 private:
@@ -93,26 +116,53 @@ class session_impl;
 
 class session {
 public:
+  // Starts HTTP/2 session by connecting to |host| and |service|
+  // (e.g., "80") using clear text TCP connection.
   session(boost::asio::io_service &io_service, const std::string &host,
           const std::string &service);
+
+  // Starts HTTP/2 session by connecting to |host| and |service|
+  // (e.g., "443") using encrypted SSL/TLS connection.
   session(boost::asio::io_service &io_service,
           boost::asio::ssl::context &tls_context, const std::string &host,
           const std::string &service);
   ~session();
 
+  // Sets callback which is invoked after connection is established.
   void on_connect(connect_cb cb) const;
+
+  // Sets callback which is invoked there is connection level error
+  // and session is terminated.
   void on_error(error_cb cb) const;
 
+  // Shutdowns connection.
   void shutdown() const;
 
+  // Returns underlying io_service object.
   boost::asio::io_service &io_service() const;
 
+  // Submits request to server using |method| (e.g., "GET"), |uri|
+  // (e.g., "http://localhost/") and optionally additional header
+  // fields.  This function returns pointer to request object if it
+  // succeeds, or nullptr and |ec| contains error message.
   const request *submit(boost::system::error_code &ec,
                         const std::string &method, const std::string &uri,
                         header_map h = {}) const;
+
+  // Submits request to server using |method| (e.g., "GET"), |uri|
+  // (e.g., "http://localhost/") and optionally additional header
+  // fields.  The |data| is request body.  This function returns
+  // pointer to request object if it succeeds, or nullptr and |ec|
+  // contains error message.
   const request *submit(boost::system::error_code &ec,
                         const std::string &method, const std::string &uri,
                         std::string data, header_map h = {}) const;
+
+  // Submits request to server using |method| (e.g., "GET"), |uri|
+  // (e.g., "http://localhost/") and optionally additional header
+  // fields.  The |cb| is used to generate request body.  This
+  // function returns pointer to request object if it succeeds, or
+  // nullptr and |ec| contains error message.
   const request *submit(boost::system::error_code &ec,
                         const std::string &method, const std::string &uri,
                         read_cb cb, header_map h = {}) const;

src/includes/nghttp2/asio_http2_server.h

@@ -42,8 +42,8 @@ public:
   request();
   ~request();
 
-  // Returns request headers.  The pusedo headers, which start with
-  // colon (:), are exluced from this list.
+  // Returns request header fields.  The pusedo header fields, which
+  // start with colon (:), are exluced from this list.
   const header_map &header() const;
 
   // Returns method (e.g., GET).
@@ -52,7 +52,8 @@ public:
   // Returns request URI, split into components.
   const uri_ref &uri() const;
 
-  // Sets callback when chunk of request body is received.
+  // Sets callback which is invoked when chunk of request body is
+  // received.
   void on_data(data_cb cb) const;
 
   // Application must not call this directly.
@@ -69,28 +70,33 @@ public:
   ~response();
 
   // Write response header using |status_code| (e.g., 200) and
-  // additional headers in |h|.
+  // additional header fields in |h|.
   void write_head(unsigned int status_code, header_map h = {}) const;
 
   // Sends |data| as request body.  No further call of end() is
   // allowed.
   void end(std::string data = "") const;
 
-  // Sets callback |cb| as a generator of the response body.  No
-  // further call of end() is allowed.
+  // Sets callback as a generator of the response body.  No further
+  // call of end() is allowed.
   void end(read_cb cb) const;
 
+  // Sets callback which is invoked when this request and response are
+  // finished.  After the invocation of this callback, the application
+  // must not access request and response object.
   void on_close(close_cb cb) const;
 
+  // Cancels this request and response with given error code.
   void cancel(uint32_t error_code = NGHTTP2_INTERNAL_ERROR) const;
 
   // Resumes deferred response.
   void resume() const;
 
   // Pushes resource denoted by |raw_path_query| using |method|.  The
-  // additional headers can be given in |h|.  This function returns
-  // pointer to response object for promised stream, otherwise nullptr
-  // and error code is filled in |ec|.
+  // additional header fields can be given in |h|.  This function
+  // returns pointer to response object for promised stream, otherwise
+  // nullptr and error code is filled in |ec|.  Be aware that the
+  // header field name given in |h| must be lower-cased.
   const response *push(boost::system::error_code &ec, std::string method,
                        std::string raw_path_query, header_map h = {}) const;
 
@@ -108,7 +114,9 @@ private:
 };
 
 // This is so called request callback.  Called every time request is
-// received.
+// received.  The life time of |request| and |response| objects end
+// when callback set by response::on_close() is called.  After that,
+// the application must not access to those objects.
 typedef std::function<void(const request &, const response &)> request_cb;
 
 class http2_impl;
@@ -124,7 +132,9 @@ public:
 
   // Registers request handler |cb| with path pattern |pattern|.  This
   // function will fail and returns false if same pattern has been
-  // already registered.  Otherwise returns true.
+  // already registered or |pattern| is empty string.  Otherwise
+  // returns true.  The pattern match rule is the same as
+  // net/http/ServeMux in golang.
   bool handle(std::string pattern, request_cb cb);
 
   // Sets number of native threads to handle incoming HTTP request.