Apply Mongoose docs edits by Ev

PUBLISHED_FROM=5cd78790a03580aa23dd3d2d8b825ad449083cc2

docs/c-api/http.h/mg_connect_http.md

@@ -10,16 +10,16 @@ signature: |
                                         const char *post_data);
 ---
 
-Helper function that creates outbound HTTP connection.
+Helper function that creates an outbound HTTP connection.
 
 `url` is a URL to fetch. It must be properly URL-encoded, e.g. have
-no spaces, etc. By default, `mg_connect_http()` sends Connection and
-Host headers. `extra_headers` is an extra HTTP headers to send, e.g.
+no spaces, etc. By default, `mg_connect_http()` sends the Connection and
+Host headers. `extra_headers` is an extra HTTP header to send, e.g.
 `"User-Agent: my-app\r\n"`.
-If `post_data` is NULL, then GET request is created. Otherwise, POST request
-is created with the specified POST data. Note that if the data being posted
-is a form submission, the `Content-Type` header should be set accordingly
-(see example below).
+If `post_data` is NULL, then a GET request is created. Otherwise, a POST
+request is created with the specified POST data. Note that if the data being
+posted is a form submission, the `Content-Type` header should be set
+accordingly (see example below).
 
 Examples:
 

docs/c-api/http.h/mg_connect_http_opt.md

@@ -11,8 +11,9 @@ signature: |
                                             const char *post_data);
 ---
 
-Helper function that creates outbound HTTP connection.
+Helper function that creates an outbound HTTP connection.
 
-Mostly identical to mg_connect_http, but allows to provide extra parameters
-(for example, SSL parameters 
+Mostly identical to mg_connect_http, but allows you to provide extra
+*parameters
+(for example, SSL parameters) 
 

docs/c-api/http.h/mg_connect_ws.md

@@ -13,7 +13,7 @@ Helper function that creates an outbound WebSocket connection.
 
 `url` is a URL to connect to. It must be properly URL-encoded, e.g. have
 no spaces, etc. By default, `mg_connect_ws()` sends Connection and
-Host headers. `extra_headers` is an extra HTTP headers to send, e.g.
+Host headers. `extra_headers` is an extra HTTP header to send, e.g.
 `"User-Agent: my-app\r\n"`.
 If `protocol` is not NULL, then a `Sec-WebSocket-Protocol` header is sent.
 

docs/c-api/http.h/mg_connect_ws_opt.md

@@ -12,6 +12,6 @@ signature: |
 
 Helper function that creates an outbound WebSocket connection
 
-Mostly identical to mg_connect_ws, but allows to provide extra parameters
-(for example, SSL parameters 
+Mostly identical to `mg_connect_ws`, but allows to provide extra parameters
+(for example, SSL parameters) 
 

docs/c-api/http.h/mg_file_upload_handler.md

@@ -12,9 +12,10 @@ This handler can be used to implement file uploads with minimum code.
 This handler will process MG_EV_HTTP_PART_* events and store file data into
 a local file.
 `local_name_fn` will be invoked with whatever name was provided by the client
-and will expect the name of the local file to open. Return value of NULL will
-abort file upload (client will get a "403 Forbidden" response). If non-null,
-the returned string must be heap-allocated and will be freed by the caller.
+and will expect the name of the local file to open. A return value of NULL
+will abort file upload (client will get a "403 Forbidden" response). If
+non-null, the returned string must be heap-allocated and will be freed by
+the caller.
 Exception: it is ok to return the same string verbatim.
 
 Example:

docs/c-api/http.h/mg_get_http_header.md

@@ -6,7 +6,7 @@ signature: |
   struct mg_str *mg_get_http_header(struct http_message *hm, const char *name);
 ---
 
-Search and return header `name` in parsed HTTP message `hm`.
+Searches and returns the header `name` in parsed HTTP message `hm`.
 If header is not found, NULL is returned. Example:
 
     struct mg_str *host_hdr = mg_get_http_header(hm, "Host"); 

docs/c-api/http.h/mg_get_http_var.md

@@ -7,10 +7,10 @@ signature: |
                       size_t dst_len);
 ---
 
-Fetch an HTTP form variable.
+Fetches a HTTP form variable.
 
-Fetch a variable `name` from a `buf` into a buffer specified by
-`dst`, `dst_len`. Destination is always zero-terminated. Return length
-of a fetched variable. If not found, 0 is returned. `buf` must be
-valid url-encoded buffer. If destination is too small, `-1` is returned. 
+Fetches a variable `name` from a `buf` into a buffer specified by `dst`,
+`dst_len`. The destination is always zero-terminated. Returns the length of
+a fetched variable. If not found, 0 is returned. `buf` must be valid
+url-encoded buffer. If destination is too small, `-1` is returned. 
 

docs/c-api/http.h/mg_http_check_digest_auth.md

@@ -7,6 +7,6 @@ signature: |
                                 FILE *fp);
 ---
 
-Authenticate HTTP request against opened passwords file.
+Authenticates a HTTP request against an opened password file.
 Returns 1 if authenticated, 0 otherwise. 
 

docs/c-api/http.h/mg_http_create_digest_auth_header.md

@@ -9,5 +9,5 @@ signature: |
                                         const char *passwd);
 ---
 
-Create Digest authentication header for client request. 
+Creates digest authentication header for a client request. 
 

docs/c-api/http.h/mg_http_parse_header.md

@@ -7,17 +7,17 @@ signature: |
                            size_t buf_size);
 ---
 
-Parse HTTP header `hdr`. Find variable `var_name` and store it's value
-in the buffer `buf`, `buf_size`. Return 0 if variable not found, non-zero
+Parses the HTTP header `hdr`. Finds variable `var_name` and stores its value
+in the buffer `buf`, `buf_size`. Returns 0 if variable not found, non-zero
 otherwise.
 
-This function is supposed to parse
-cookies, authentication headers, etcetera. Example (error handling omitted):
+This function is supposed to parse cookies, authentication headers, etc.
+Example (error handling omitted):
 
     char user[20];
     struct mg_str *hdr = mg_get_http_header(hm, "Authorization");
     mg_http_parse_header(hdr, "username", user, sizeof(user));
 
-Return length of the variable's value. If buffer is not large enough,
+Returns the length of the variable's value. If buffer is not large enough,
 or variable not found, 0 is returned. 
 

docs/c-api/http.h/mg_parse_http.md

@@ -6,10 +6,10 @@ signature: |
   int mg_parse_http(const char *s, int n, struct http_message *hm, int is_req);
 ---
 
-Parse a HTTP message.
+Parses a HTTP message.
 
-`is_req` should be set to 1 if parsing request, 0 if reply.
+`is_req` should be set to 1 if parsing a request, 0 if reply.
 
-Return number of bytes parsed. If HTTP message is
-incomplete, `0` is returned. On parse error, negative number is returned. 
+Returns the number of bytes parsed. If HTTP message is
+incomplete `0` is returned. On parse error, a negative number is returned. 
 

docs/c-api/http.h/mg_parse_multipart.md

@@ -9,13 +9,13 @@ signature: |
                             size_t *chunk_len);
 ---
 
-Parse buffer `buf`, `buf_len` that contains multipart form data chunks.
-Store chunk name in a `var_name`, `var_name_len` buffer.
+Parses the buffer `buf`, `buf_len` that contains multipart form data chunks.
+Stores the chunk name in a `var_name`, `var_name_len` buffer.
 If a chunk is an uploaded file, then `file_name`, `file_name_len` is
 filled with an uploaded file name. `chunk`, `chunk_len`
 points to the chunk data.
 
-Return: number of bytes to skip to the next chunk, or 0 if there are
+Return: number of bytes to skip to the next chunk or 0 if there are
         no more chunks.
 
 Usage example:

docs/c-api/http.h/mg_printf_html_escape.md

@@ -6,5 +6,5 @@ signature: |
   void mg_printf_html_escape(struct mg_connection *nc, const char *fmt, ...);
 ---
 
-Send printf-formatted HTTP chunk, escaping HTML tags. 
+Sends a printf-formatted HTTP chunk, escaping HTML tags. 
 

docs/c-api/http.h/mg_printf_http_chunk.md

@@ -6,6 +6,6 @@ signature: |
   void mg_printf_http_chunk(struct mg_connection *nc, const char *fmt, ...);
 ---
 
-Send printf-formatted HTTP chunk.
+Sends a printf-formatted HTTP chunk.
 Functionality is similar to `mg_send_http_chunk()`. 
 

docs/c-api/http.h/mg_printf_websocket_frame.md

@@ -7,8 +7,8 @@ signature: |
                                  const char *fmt, ...);
 ---
 
-Send websocket frame to the remote end.
+Sends WebSocket frame to the remote end.
 
-Like `mg_send_websocket_frame()`, but allows to create formatted message
+Like `mg_send_websocket_frame()`, but allows to create formatted messages
 with `printf()`-like semantics. 
 

docs/c-api/http.h/mg_register_http_endpoint.md

@@ -7,8 +7,8 @@ signature: |
                                  mg_event_handler_t handler);
 ---
 
-Register callback for specified http endpoint
-Note: if callback is registered it is called instead of
+Registers a callback for a specified http endpoint
+Note: if callback is registered it is called instead of the
 callback provided in mg_bind
 
 Example code snippet:

docs/c-api/http.h/mg_send_head.md

@@ -7,15 +7,15 @@ signature: |
                     int64_t content_length, const char *extra_headers);
 ---
 
-Send response line and headers.
-This function sends response line with the `status_code`, and automatically
-sends one header: either "Content-Length", or "Transfer-Encoding".
+Sends a response line and headers.
+This function sends a response line with the `status_code`, and automatically
+sends one header: either "Content-Length" or "Transfer-Encoding".
 If `content_length` is negative, then "Transfer-Encoding: chunked" header
 is sent, otherwise, "Content-Length" header is sent.
 
 NOTE: If `Transfer-Encoding` is `chunked`, then message body must be sent
 using `mg_send_http_chunk()` or `mg_printf_http_chunk()` functions.
 Otherwise, `mg_send()` or `mg_printf()` must be used.
-Extra headers could be set through `extra_headers` - and note `extra_headers`
+Extra headers could be set through `extra_headers`. Note `extra_headers`
 must NOT be terminated by a new line. 
 

docs/c-api/http.h/mg_send_http_chunk.md

@@ -6,16 +6,17 @@ signature: |
   void mg_send_http_chunk(struct mg_connection *nc, const char *buf, size_t len);
 ---
 
-Send buffer `buf` of size `len` to the client using chunked HTTP encoding.
-This function first sends buffer size as hex number + newline, then
-buffer itself, then newline. For example,
-  `mg_send_http_chunk(nc, "foo", 3)` whill append `3\r\nfoo\r\n` string to
+Sends buffer `buf` of size `len` to the client using chunked HTTP encoding.
+This function sends the buffer size as hex number + newline first, then
+the buffer itself, then the newline. For example,
+  `mg_send_http_chunk(nc, "foo", 3)` whill append the `3\r\nfoo\r\n` string
+*to
 the `nc->send_mbuf` output IO buffer.
 
-NOTE: HTTP header "Transfer-Encoding: chunked" should be sent prior to
+NOTE: The HTTP header "Transfer-Encoding: chunked" should be sent prior to
 using this function.
 
-NOTE: do not forget to send empty chunk at the end of the response,
+NOTE: do not forget to send an empty chunk at the end of the response,
 to tell the client that everything was sent. Example:
 
 ```

docs/c-api/http.h/mg_send_response_line.md

@@ -7,7 +7,7 @@ signature: |
                              const char *extra_headers);
 ---
 
-Send response status line.
+Sends a response status line.
 If `extra_headers` is not NULL, then `extra_headers` are also sent
 after the reponse line. `extra_headers` must NOT end end with new line.
 Example:

docs/c-api/http.h/mg_send_websocket_frame.md

@@ -7,9 +7,9 @@ signature: |
                                const void *data, size_t data_len);
 ---
 
-Send websocket frame to the remote end.
+Send WebSocket frame to the remote end.
 
-`op_and_flags` specifies frame's type, one of:
+`op_and_flags` specifies the frame's type. It's one of:
 
 - WEBSOCKET_OP_CONTINUE
 - WEBSOCKET_OP_TEXT

docs/c-api/http.h/mg_send_websocket_framev.md

@@ -7,7 +7,7 @@ signature: |
                                 const struct mg_str *strings, int num_strings);
 ---
 
-Send multiple websocket frames.
+Sends multiple websocket frames.
 
 Like `mg_send_websocket_frame()`, but composes a frame from multiple buffers. 
 

docs/c-api/http.h/mg_serve_http.md

@@ -7,7 +7,7 @@ signature: |
                      struct mg_serve_http_opts opts);
 ---
 
-Serve given HTTP request according to the `options`.
+Serves given HTTP request according to the `options`.
 
 Example code snippet:
 

docs/c-api/http.h/mg_set_protocol_http_websocket.md

@@ -6,40 +6,41 @@ signature: |
   void mg_set_protocol_http_websocket(struct mg_connection *nc);
 ---
 
-Attach built-in HTTP event handler to the given connection.
-User-defined event handler will receive following extra events:
+Attaches a built-in HTTP event handler to the given connection.
+The user-defined event handler will receive following extra events:
 
 - MG_EV_HTTP_REQUEST: HTTP request has arrived. Parsed HTTP request
  is passed as
   `struct http_message` through the handler's `void *ev_data` pointer.
 - MG_EV_HTTP_MULTIPART_REQUEST: A multipart POST request has received.
-  This event is sent before body is parsed. After this user
+  This event is sent before body is parsed. After this, the user
   should expect a sequence of MG_EV_HTTP_PART_BEGIN/DATA/END requests.
   This is also the last time when headers and other request fields are
   accessible.
-- MG_EV_HTTP_REPLY: HTTP reply has arrived. Parsed HTTP reply is passed as
-  `struct http_message` through the handler's `void *ev_data` pointer.
-- MG_EV_HTTP_CHUNK: HTTP chunked-encoding chunk has arrived.
-  Parsed HTTP reply is passed as `struct http_message` through the
+- MG_EV_HTTP_REPLY: The HTTP reply has arrived. The parsed HTTP reply is
+  passed as `struct http_message` through the handler's `void *ev_data`
+  pointer.
+- MG_EV_HTTP_CHUNK: The HTTP chunked-encoding chunk has arrived.
+  The parsed HTTP reply is passed as `struct http_message` through the
   handler's `void *ev_data` pointer. `http_message::body` would contain
   incomplete, reassembled HTTP body.
-  It will grow with every new chunk arrived, and
-  potentially can consume a lot of memory. An event handler may process
+  It will grow with every new chunk that arrives, and it can
+  potentially consume a lot of memory. An event handler may process
   the body as chunks are coming, and signal Mongoose to delete processed
   body by setting `MG_F_DELETE_CHUNK` in `mg_connection::flags`. When
   the last zero chunk is received,
   Mongoose sends `MG_EV_HTTP_REPLY` event with
   full reassembled body (if handler did not signal to delete chunks) or
   with empty body (if handler did signal to delete chunks).
-- MG_EV_WEBSOCKET_HANDSHAKE_REQUEST: server has received websocket handshake
-  request. `ev_data` contains parsed HTTP request.
-- MG_EV_WEBSOCKET_HANDSHAKE_DONE: server has completed Websocket handshake.
-  `ev_data` is `NULL`.
-- MG_EV_WEBSOCKET_FRAME: new websocket frame has arrived. `ev_data` is
+- MG_EV_WEBSOCKET_HANDSHAKE_REQUEST: server has received the WebSocket
+  handshake request. `ev_data` contains parsed HTTP request.
+- MG_EV_WEBSOCKET_HANDSHAKE_DONE: server has completed the WebSocket
+  handshake. `ev_data` is `NULL`.
+- MG_EV_WEBSOCKET_FRAME: new WebSocket frame has arrived. `ev_data` is
   `struct websocket_message *`
 - MG_EV_HTTP_PART_BEGIN: new part of multipart message is started,
   extra parameters are passed in mg_http_multipart_part
-- MG_EV_HTTP_PART_DATA: new portion of data from multiparted message
+- MG_EV_HTTP_PART_DATA: new portion of data from the multiparted message
   no additional headers are available, only data and data size
 - MG_EV_HTTP_PART_END: final boundary received, analogue to maybe used to
   find the end of packet

docs/c-api/http.h/mg_url_decode.md

@@ -7,12 +7,12 @@ signature: |
                     int is_form_url_encoded);
 ---
 
-Decode URL-encoded string.
+Decodes URL-encoded string.
 
 Source string is specified by (`src`, `src_len`), and destination is
 (`dst`, `dst_len`). If `is_form_url_encoded` is non-zero, then
 `+` character is decoded as a blank space character. This function
 guarantees to `\0`-terminate the destination. If destination is too small,
-then source string is partially decoded and `-1` is returned. Otherwise,
+then the source string is partially decoded and `-1` is returned. Otherwise,
 a length of decoded string is returned, not counting final `\0`.