diff --git a/docs/c-api/coap.h/mg_coap_add_option.md b/docs/c-api/coap.h/mg_coap_add_option.md
index f56887e5d5fb119d24fdb1956df78621fb6f13e6..5867b7b78e12647c25313c3cb041d7ff14e12d0b 100644
--- a/docs/c-api/coap.h/mg_coap_add_option.md
+++ b/docs/c-api/coap.h/mg_coap_add_option.md
@@ -8,6 +8,6 @@ signature: |
size_t len);
---
-Add new option to mg_coap_message structure.
+Adds a new option to mg_coap_message structure.
Returns pointer to the newly created option.
diff --git a/docs/c-api/coap.h/mg_coap_free_options.md b/docs/c-api/coap.h/mg_coap_free_options.md
index 39d07d443dda1eae62f8d146b1e47270d0840535..9dcc816f471af97be5a1e1721d341ff3f202c864 100644
--- a/docs/c-api/coap.h/mg_coap_free_options.md
+++ b/docs/c-api/coap.h/mg_coap_free_options.md
@@ -6,6 +6,6 @@ signature: |
void mg_coap_free_options(struct mg_coap_message *cm);
---
-Free the memory allocated for options,
-if cm paramater doesn't contain any option does nothing.
+Frees the memory allocated for options.
+If the cm paramater doesn't contain any option it does nothing.
diff --git a/docs/c-api/coap.h/mg_coap_parse.md b/docs/c-api/coap.h/mg_coap_parse.md
index 2f3bc0c6505d1fb73cf0cd5540fc53843b0b8a2a..86885229d0c6a084b466ae7f65973f1b450be45c 100644
--- a/docs/c-api/coap.h/mg_coap_parse.md
+++ b/docs/c-api/coap.h/mg_coap_parse.md
@@ -6,13 +6,13 @@ signature: |
uint32_t mg_coap_parse(struct mbuf *io, struct mg_coap_message *cm);
---
-Parse COAP message and fills mg_coap_message and returns cm->flags.
+Parses CoAP message and fills mg_coap_message and returns cm->flags.
This is a helper function.
-NOTE: usually CoAP work over UDP, so lack of data means format error,
-but in theory it is possible to use CoAP over TCP (according to RFC)
+NOTE: usually CoAP works over UDP, so lack of data means format error.
+But, in theory, it is possible to use CoAP over TCP (according to RFC)
-The caller have to check results and treat COAP_NOT_ENOUGH_DATA according to
+The caller has to check results and treat COAP_NOT_ENOUGH_DATA according to
underlying protocol:
- in case of UDP COAP_NOT_ENOUGH_DATA means COAP_FORMAT_ERROR,
diff --git a/docs/c-api/coap.h/mg_coap_send_ack.md b/docs/c-api/coap.h/mg_coap_send_ack.md
index 5cdd0c1d1a74eeb0bd89315fc598a64f703afb7e..1475a9c58c5dea0ee20c8a8abd192bede3ea1d58 100644
--- a/docs/c-api/coap.h/mg_coap_send_ack.md
+++ b/docs/c-api/coap.h/mg_coap_send_ack.md
@@ -6,7 +6,7 @@ signature: |
uint32_t mg_coap_send_ack(struct mg_connection *nc, uint16_t msg_id);
---
-Compose CoAP acknowledgement from `mg_coap_message`
-and send it into `nc` connection.
+Composes CoAP acknowledgement from `mg_coap_message`
+and sends it into `nc` connection.
Return value: see `mg_coap_send_message()`
diff --git a/docs/c-api/coap.h/mg_coap_send_message.md b/docs/c-api/coap.h/mg_coap_send_message.md
index 34bf3c87cc484a854f8fc14f65ffc11271c6bd33..a1acc01e5fa04c7659699d2ca1cc0eb06c58cd63 100644
--- a/docs/c-api/coap.h/mg_coap_send_message.md
+++ b/docs/c-api/coap.h/mg_coap_send_message.md
@@ -7,9 +7,9 @@ signature: |
struct mg_coap_message *cm);
---
-Compose CoAP message from `mg_coap_message`
-and send it into `nc` connection.
-Return 0 on success. On error, it is a bitmask:
+Composes a CoAP message from `mg_coap_message`
+and sends it into `nc` connection.
+Returns 0 on success. On error, it is a bitmask:
- `#define MG_COAP_ERROR 0x10000`
- `#define MG_COAP_FORMAT_ERROR (MG_COAP_ERROR | 0x20000)`
diff --git a/docs/c-api/coap.h/mg_set_protocol_coap.md b/docs/c-api/coap.h/mg_set_protocol_coap.md
index 60981fb6b5b4da59e869b5359cec0d1ea7ca5cd3..523ae7cb4c34574c09842180488d90d7dd91a678 100644
--- a/docs/c-api/coap.h/mg_set_protocol_coap.md
+++ b/docs/c-api/coap.h/mg_set_protocol_coap.md
@@ -6,5 +6,5 @@ signature: |
int mg_set_protocol_coap(struct mg_connection *nc);
---
-Set CoAP protocol handler - trigger CoAP specific events
+Sets CoAP protocol handler - triggers CoAP specific events.
diff --git a/docs/c-api/dns-server.h/mg_dns_create_reply.md b/docs/c-api/dns-server.h/mg_dns_create_reply.md
index b616c925de60b7a44509b6c3b0c8c22de696823d..40c6f225d5f60a038df2a23b8191c7feb6457498 100644
--- a/docs/c-api/dns-server.h/mg_dns_create_reply.md
+++ b/docs/c-api/dns-server.h/mg_dns_create_reply.md
@@ -7,18 +7,18 @@ signature: |
struct mg_dns_message *msg);
---
-Create a DNS reply.
+Creates a DNS reply.
The reply will be based on an existing query message `msg`.
The query body will be appended to the output buffer.
-"reply + recursion allowed" will be added to the message flags and
+"reply + recursion allowed" will be added to the message flags and the
message's num_answers will be set to 0.
Answer records can be appended with `mg_dns_send_reply` or by lower
level function defined in the DNS API.
-In order to send the reply use `mg_dns_send_reply`.
-It's possible to use a connection's send buffer as reply buffers,
+In order to send a reply use `mg_dns_send_reply`.
+It's possible to use a connection's send buffer as reply buffer,
and it will work for both UDP and TCP connections.
Example:
diff --git a/docs/c-api/dns-server.h/mg_dns_reply_record.md b/docs/c-api/dns-server.h/mg_dns_reply_record.md
index a247c8eca353630c2aca5246d3c59e2b52856486..408f705f078dbd5eabb020da6b8f7e7bb49ae9e0 100644
--- a/docs/c-api/dns-server.h/mg_dns_reply_record.md
+++ b/docs/c-api/dns-server.h/mg_dns_reply_record.md
@@ -9,10 +9,10 @@ signature: |
size_t rdata_len);
---
-Append a DNS reply record to the IO buffer and to the DNS message.
+Appends a DNS reply record to the IO buffer and to the DNS message.
-The message num_answers field will be incremented. It's caller's duty
-to ensure num_answers is propertly initialized.
+The message's num_answers field will be incremented. It's the caller's duty
+to ensure num_answers is properly initialised.
Returns -1 on error.
diff --git a/docs/c-api/dns-server.h/mg_dns_send_reply.md b/docs/c-api/dns-server.h/mg_dns_send_reply.md
index d5b15de497be895bfc11f680a0b43aed5aa6a7bc..0460e7310949a524535fe647da48a6bc20cba7fe 100644
--- a/docs/c-api/dns-server.h/mg_dns_send_reply.md
+++ b/docs/c-api/dns-server.h/mg_dns_send_reply.md
@@ -6,12 +6,12 @@ signature: |
void mg_dns_send_reply(struct mg_connection *nc, struct mg_dns_reply *r);
---
-Send a DNS reply through a connection.
+Sends a DNS reply through a connection.
The DNS data is stored in an IO buffer pointed by reply structure in `r`.
This function mutates the content of that buffer in order to ensure that
-the DNS header reflects size and flags of the mssage, that might have been
-updated either with `mg_dns_reply_record` or by direct manipulation of
+the DNS header reflects the size and flags of the message, that might have
+been updated either with `mg_dns_reply_record` or by direct manipulation of
`r->message`.
Once sent, the IO buffer will be trimmed unless the reply IO buffer
diff --git a/docs/c-api/dns.h/mg_dns_copy_questions.md b/docs/c-api/dns.h/mg_dns_copy_questions.md
index 9fc2091fb0309be857a3516c11fb974644fc448c..f6f7dcb76adf741358574671963c184d53250ff3 100644
--- a/docs/c-api/dns.h/mg_dns_copy_questions.md
+++ b/docs/c-api/dns.h/mg_dns_copy_questions.md
@@ -6,10 +6,10 @@ signature: |
int mg_dns_copy_questions(struct mbuf *io, struct mg_dns_message *msg);
---
-Append already encoded questions from an existing message.
+Appends already encoded questions from an existing message.
This is useful when generating a DNS reply message which includes
all question records.
-Return number of appened bytes.
+Returns the number of appended bytes.
diff --git a/docs/c-api/dns.h/mg_dns_encode_record.md b/docs/c-api/dns.h/mg_dns_encode_record.md
index 4b8a985045bf984a012c694e85458687a7fef1e6..a892e5de5f7865fcd947ec57545384dfa0e1365c 100644
--- a/docs/c-api/dns.h/mg_dns_encode_record.md
+++ b/docs/c-api/dns.h/mg_dns_encode_record.md
@@ -8,11 +8,11 @@ signature: |
size_t rlen);
---
-Encode and append a DNS resource record to an IO buffer.
+Encodes and appends a DNS resource record to an IO buffer.
The record metadata is taken from the `rr` parameter, while the name and data
are taken from the parameters, encoded in the appropriate format depending on
-record type, and stored in the IO buffer. The encoded values might contain
+record type and stored in the IO buffer. The encoded values might contain
offsets within the IO buffer. It's thus important that the IO buffer doesn't
get trimmed while a sequence of records are encoded while preparing a DNS
*reply.
@@ -21,5 +21,5 @@ This function doesn't update the `name` and `rdata` pointers in the `rr`
*struct
because they might be invalidated as soon as the IO buffer grows again.
-Return the number of bytes appened or -1 in case of error.
+Returns the number of bytes appened or -1 in case of error.
diff --git a/docs/c-api/dns.h/mg_dns_insert_header.md b/docs/c-api/dns.h/mg_dns_insert_header.md
index 0a9d7dae400d4615bc7a8bf87202fe4c465ab63b..52b2ac3efa8adfc33ab6684cefd9d2f611328f94 100644
--- a/docs/c-api/dns.h/mg_dns_insert_header.md
+++ b/docs/c-api/dns.h/mg_dns_insert_header.md
@@ -7,7 +7,7 @@ signature: |
struct mg_dns_message *msg);
---
-Insert a DNS header to an IO buffer.
+Inserts a DNS header to an IO buffer.
-Return number of bytes inserted.
+Returns the number of bytes inserted.
diff --git a/docs/c-api/dns.h/mg_dns_parse_record_data.md b/docs/c-api/dns.h/mg_dns_parse_record_data.md
index d8239befe9cfa8990f93f7e2c94259111deabd35..efe56ef4a065fc595d619dd55464afb46ac23b87 100644
--- a/docs/c-api/dns.h/mg_dns_parse_record_data.md
+++ b/docs/c-api/dns.h/mg_dns_parse_record_data.md
@@ -8,7 +8,7 @@ signature: |
size_t data_len);
---
-Parse the record data from a DNS resource record.
+Parses the record data from a DNS resource record.
- A: struct in_addr *ina
- AAAA: struct in6_addr *ina
diff --git a/docs/c-api/dns.h/mg_dns_uncompress_name.md b/docs/c-api/dns.h/mg_dns_uncompress_name.md
index 3db03df896583580608e4721501fe1de676797e1..5e5fa53b001fc7b05d381855241656d5df2a3255 100644
--- a/docs/c-api/dns.h/mg_dns_uncompress_name.md
+++ b/docs/c-api/dns.h/mg_dns_uncompress_name.md
@@ -7,15 +7,15 @@ signature: |
char *dst, int dst_len);
---
-Uncompress a DNS compressed name.
+Uncompresses a DNS compressed name.
-The containing dns message is required because the compressed encoding
+The containing DNS message is required because of the compressed encoding
and reference suffixes present elsewhere in the packet.
-If name is less than `dst_len` characters long, the remainder
-of `dst` is terminated with `\0' characters. Otherwise, `dst` is not
-*terminated.
+If the name is less than `dst_len` characters long, the remainder
+of `dst` is terminated with `\0` characters. Otherwise, `dst` is not
+terminated.
If `dst_len` is 0 `dst` can be NULL.
-Return the uncompressed name length.
+Returns the uncompressed name length.
diff --git a/docs/c-api/dns.h/mg_send_dns_query.md b/docs/c-api/dns.h/mg_send_dns_query.md
index 5dd22c3682a4477db9637f903f31ff836a828a88..a6b15da96ff28e1a9cbedf60b71a3ef12ecd1ad6 100644
--- a/docs/c-api/dns.h/mg_send_dns_query.md
+++ b/docs/c-api/dns.h/mg_send_dns_query.md
@@ -7,5 +7,5 @@ signature: |
int query_type);
---
-Send a DNS query to the remote end.
+Sends a DNS query to the remote end.
diff --git a/docs/c-api/dns.h/mg_set_protocol_dns.md b/docs/c-api/dns.h/mg_set_protocol_dns.md
index 7d7d0dc4fa89bac97c3948f3d425ba49f50a302a..fdf5ab59e62c73646be2372baf1e35236e705a54 100644
--- a/docs/c-api/dns.h/mg_set_protocol_dns.md
+++ b/docs/c-api/dns.h/mg_set_protocol_dns.md
@@ -6,11 +6,11 @@ signature: |
void mg_set_protocol_dns(struct mg_connection *nc);
---
-Attach built-in DNS event handler to the given listening connection.
+Attaches a built-in DNS event handler to the given listening connection.
-DNS event handler parses incoming UDP packets, treating them as DNS
-requests. If incoming packet gets successfully parsed by the DNS event
-handler, a user event handler will receive `MG_DNS_REQUEST` event, with
+The DNS event handler parses the incoming UDP packets, treating them as DNS
+requests. If an incoming packet gets successfully parsed by the DNS event
+handler, a user event handler will receive an `MG_DNS_REQUEST` event, with
`ev_data` pointing to the parsed `struct mg_dns_message`.
See
diff --git a/docs/c-api/http.h/mg_connect_http.md b/docs/c-api/http.h/mg_connect_http.md
index b897be0ce903f9ac554117935c8dcc080554d71d..c99d80d72f6d4065125a45952769e859d3e3ca58 100644
--- a/docs/c-api/http.h/mg_connect_http.md
+++ b/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:
diff --git a/docs/c-api/http.h/mg_connect_http_opt.md b/docs/c-api/http.h/mg_connect_http_opt.md
index be68a67f0168aff8c1bb6847c7ac630aff3e372a..2454cb10ee06712997b4a9e6c088d12ff7b5e3f4 100644
--- a/docs/c-api/http.h/mg_connect_http_opt.md
+++ b/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)
diff --git a/docs/c-api/http.h/mg_connect_ws.md b/docs/c-api/http.h/mg_connect_ws.md
index 417279c86129e797f733aebe18d7dd1b69d4d00e..b0f38d74895f3a5c6222457a6189a10ac345c160 100644
--- a/docs/c-api/http.h/mg_connect_ws.md
+++ b/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.
diff --git a/docs/c-api/http.h/mg_connect_ws_opt.md b/docs/c-api/http.h/mg_connect_ws_opt.md
index 3ab91083dd381eca6700c524277ea5cf9c8165b2..57956ddbd30fbb22ef7582589574f9b40240ce8a 100644
--- a/docs/c-api/http.h/mg_connect_ws_opt.md
+++ b/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)
diff --git a/docs/c-api/http.h/mg_file_upload_handler.md b/docs/c-api/http.h/mg_file_upload_handler.md
index b0459676fe1f50c6a3392b867d81086d941b8839..444c106ff2b4a6713099ff455e961575da006f6b 100644
--- a/docs/c-api/http.h/mg_file_upload_handler.md
+++ b/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:
diff --git a/docs/c-api/http.h/mg_get_http_header.md b/docs/c-api/http.h/mg_get_http_header.md
index 5c6d85ba1dc8c388b5e64f60072b43911aedf94f..b33e91f48c166a16a171b2f9e89bfbeaa1be1c35 100644
--- a/docs/c-api/http.h/mg_get_http_header.md
+++ b/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");
diff --git a/docs/c-api/http.h/mg_get_http_var.md b/docs/c-api/http.h/mg_get_http_var.md
index cc54c2ebe9f46880e1bd3b57f5f91cad68555465..55ee3e6fdc0eb5b35a1477866e469df1f1033577 100644
--- a/docs/c-api/http.h/mg_get_http_var.md
+++ b/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.
diff --git a/docs/c-api/http.h/mg_http_check_digest_auth.md b/docs/c-api/http.h/mg_http_check_digest_auth.md
index 99cb66d7a833d96d6ba70b7bfb5ce281fb614a59..3494eb261a0efdb506c00d9a2440114bf38b17b9 100644
--- a/docs/c-api/http.h/mg_http_check_digest_auth.md
+++ b/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.
diff --git a/docs/c-api/http.h/mg_http_create_digest_auth_header.md b/docs/c-api/http.h/mg_http_create_digest_auth_header.md
index dd98fdc1d1d855a7c3390cabe6986f2d11969a9c..67b2eab8de73c063dec693fe0b730b308e300714 100644
--- a/docs/c-api/http.h/mg_http_create_digest_auth_header.md
+++ b/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.
diff --git a/docs/c-api/http.h/mg_http_parse_header.md b/docs/c-api/http.h/mg_http_parse_header.md
index cd7beb6e035e084299ad6646726186b3713cadea..f86564536ab146012c4b3582eba071812a00d0ff 100644
--- a/docs/c-api/http.h/mg_http_parse_header.md
+++ b/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.
diff --git a/docs/c-api/http.h/mg_parse_http.md b/docs/c-api/http.h/mg_parse_http.md
index 068ddc16d647c1ac4c7078af93b8e351bc6e9f37..fdd5c638f41eba8dfe6fca6c72bf1860c2d04f42 100644
--- a/docs/c-api/http.h/mg_parse_http.md
+++ b/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.
diff --git a/docs/c-api/http.h/mg_parse_multipart.md b/docs/c-api/http.h/mg_parse_multipart.md
index 3eb82cdb7e9266326ad49eded920efd7ba54e1a6..f98d48fad6edc2657e0094fbb3dce187b634e84a 100644
--- a/docs/c-api/http.h/mg_parse_multipart.md
+++ b/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:
diff --git a/docs/c-api/http.h/mg_printf_html_escape.md b/docs/c-api/http.h/mg_printf_html_escape.md
index fd1ff3e0a7fc0ee7ccb7c9293d84acf2b9eefdaa..6238e28d1a1ad2d22b13d1646e581e30db352fd7 100644
--- a/docs/c-api/http.h/mg_printf_html_escape.md
+++ b/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.
diff --git a/docs/c-api/http.h/mg_printf_http_chunk.md b/docs/c-api/http.h/mg_printf_http_chunk.md
index a8e6d1427657bf4ea4afb0723b901cc8da30c2ca..f99324b23a107f001404b8e69359ca9e358cac0f 100644
--- a/docs/c-api/http.h/mg_printf_http_chunk.md
+++ b/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()`.
diff --git a/docs/c-api/http.h/mg_printf_websocket_frame.md b/docs/c-api/http.h/mg_printf_websocket_frame.md
index a656129999c06fda1a33f2eff06fc1ce36264341..a7e8944bbb45eeab343110e9d06e2c9708304fa1 100644
--- a/docs/c-api/http.h/mg_printf_websocket_frame.md
+++ b/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.
diff --git a/docs/c-api/http.h/mg_register_http_endpoint.md b/docs/c-api/http.h/mg_register_http_endpoint.md
index eefbe99e0fea04530585e746d50c81cce42d1f37..752eaae6b02ef138c3db4b8f794928abbd169705 100644
--- a/docs/c-api/http.h/mg_register_http_endpoint.md
+++ b/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:
diff --git a/docs/c-api/http.h/mg_send_head.md b/docs/c-api/http.h/mg_send_head.md
index cd18d36c987083bec4e0dca52a8cdfdfaa58c581..698c8cd845fe157bafb246607b1583a7857cb33f 100644
--- a/docs/c-api/http.h/mg_send_head.md
+++ b/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.
diff --git a/docs/c-api/http.h/mg_send_http_chunk.md b/docs/c-api/http.h/mg_send_http_chunk.md
index 6d017fbbe153e652b50194c95935933feccc61f9..8ad31e5e89dc1ce01b3f2eecc352eb3e69d4a9b6 100644
--- a/docs/c-api/http.h/mg_send_http_chunk.md
+++ b/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:
```
diff --git a/docs/c-api/http.h/mg_send_response_line.md b/docs/c-api/http.h/mg_send_response_line.md
index 8f62d717fdbe90de741d8d289f62fab0ad0e4bba..bd72b0da47a9570e2a973a9e240cc1f37a562849 100644
--- a/docs/c-api/http.h/mg_send_response_line.md
+++ b/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:
diff --git a/docs/c-api/http.h/mg_send_websocket_frame.md b/docs/c-api/http.h/mg_send_websocket_frame.md
index bcc5d0c57c37fdc4b72decbba5302c2c4626dee8..8a407a68a9092c0dfb2a7e86cc383de2d45feb5b 100644
--- a/docs/c-api/http.h/mg_send_websocket_frame.md
+++ b/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
diff --git a/docs/c-api/http.h/mg_send_websocket_framev.md b/docs/c-api/http.h/mg_send_websocket_framev.md
index 4eb3709f950e9b36739abb7a6489bbf3bed8c23d..005a7916527a68b4d1d592c8cc42cd7e76b4bb7c 100644
--- a/docs/c-api/http.h/mg_send_websocket_framev.md
+++ b/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.
diff --git a/docs/c-api/http.h/mg_serve_http.md b/docs/c-api/http.h/mg_serve_http.md
index 22b326887998a1cd3c4f4c1e612bdd49ae7f0fef..980695036d4710f215d08a615a6e35d7ec7874aa 100644
--- a/docs/c-api/http.h/mg_serve_http.md
+++ b/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:
diff --git a/docs/c-api/http.h/mg_set_protocol_http_websocket.md b/docs/c-api/http.h/mg_set_protocol_http_websocket.md
index 9dcefcba34de438c77ad0784dd1e6238af272914..3229b651828f723dbab575b593ec0b923e07a72d 100644
--- a/docs/c-api/http.h/mg_set_protocol_http_websocket.md
+++ b/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
diff --git a/docs/c-api/http.h/mg_url_decode.md b/docs/c-api/http.h/mg_url_decode.md
index 9e2f7e783f33b272ee2afce55371c2e04754561b..b0edaadaef3d9bed3f9568aab7fa02aa4f6c9c64 100644
--- a/docs/c-api/http.h/mg_url_decode.md
+++ b/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`.
diff --git a/docs/c-api/mqtt-broker.h/mg_mqtt_broker.md b/docs/c-api/mqtt-broker.h/mg_mqtt_broker.md
index 2532bc6fdfb44cdcb212174d4727ae542b8407aa..613cfc178de08088fa96050f2f70a8e322f3af64 100644
--- a/docs/c-api/mqtt-broker.h/mg_mqtt_broker.md
+++ b/docs/c-api/mqtt-broker.h/mg_mqtt_broker.md
@@ -6,10 +6,10 @@ signature: |
void mg_mqtt_broker(struct mg_connection *brk, int ev, void *data);
---
-Process a MQTT broker message.
+Processes a MQTT broker message.
-Listening connection expects a pointer to an initialized `mg_mqtt_broker`
-structure in the `user_data` field.
+The listening connection expects a pointer to an initialised
+`mg_mqtt_broker` structure in the `user_data` field.
Basic usage:
diff --git a/docs/c-api/mqtt-broker.h/mg_mqtt_broker_init.md b/docs/c-api/mqtt-broker.h/mg_mqtt_broker_init.md
index 74b7e5db78e7b9434e3051755e06ca92f1f530dd..9c19bd893d768d4330ce0dd03554cb318f6c14a7 100644
--- a/docs/c-api/mqtt-broker.h/mg_mqtt_broker_init.md
+++ b/docs/c-api/mqtt-broker.h/mg_mqtt_broker_init.md
@@ -6,5 +6,5 @@ signature: |
void mg_mqtt_broker_init(struct mg_mqtt_broker *brk, void *user_data);
---
-Initialize a MQTT broker.
+Initialises a MQTT broker.
diff --git a/docs/c-api/mqtt.h/mg_mqtt_connack.md b/docs/c-api/mqtt.h/mg_mqtt_connack.md
index 3b22d0a0f42315f8b4d95a3cb2a9e6b3a71f7ab3..7daaf5b425c688f50d49856ff9562b79af0edffb 100644
--- a/docs/c-api/mqtt.h/mg_mqtt_connack.md
+++ b/docs/c-api/mqtt.h/mg_mqtt_connack.md
@@ -6,5 +6,5 @@ signature: |
void mg_mqtt_connack(struct mg_connection *nc, uint8_t return_code);
---
-Send a CONNACK command with a given `return_code`.
+Sends a CONNACK command with a given `return_code`.
diff --git a/docs/c-api/mqtt.h/mg_mqtt_disconnect.md b/docs/c-api/mqtt.h/mg_mqtt_disconnect.md
index 2437c21d4957c366ef2a3a460d6a02c1c6c27d7c..c727cad0624b8c156165dd87774350ff19004b3a 100644
--- a/docs/c-api/mqtt.h/mg_mqtt_disconnect.md
+++ b/docs/c-api/mqtt.h/mg_mqtt_disconnect.md
@@ -6,5 +6,5 @@ signature: |
void mg_mqtt_disconnect(struct mg_connection *nc);
---
-Send a DISCONNECT command.
+Sends a DISCONNECT command.
diff --git a/docs/c-api/mqtt.h/mg_mqtt_next_subscribe_topic.md b/docs/c-api/mqtt.h/mg_mqtt_next_subscribe_topic.md
index 3e7eeab52868ec3608b6505cbd79c1e9ce837136..ccb96e6208974b9f8ed6a0f5569aabf296c0f509 100644
--- a/docs/c-api/mqtt.h/mg_mqtt_next_subscribe_topic.md
+++ b/docs/c-api/mqtt.h/mg_mqtt_next_subscribe_topic.md
@@ -7,9 +7,9 @@ signature: |
struct mg_str *topic, uint8_t *qos, int pos);
---
-Extract the next topic expression from a SUBSCRIBE command payload.
+Extracts the next topic expression from a SUBSCRIBE command payload.
-Topic expression name will point to a string in the payload buffer.
-Return the pos of the next topic expression or -1 when the list
+The topic expression name will point to a string in the payload buffer.
+Returns the pos of the next topic expression or -1 when the list
of topics is exhausted.
diff --git a/docs/c-api/mqtt.h/mg_mqtt_ping.md b/docs/c-api/mqtt.h/mg_mqtt_ping.md
index acaa11ac5bf66ffedc63ba2b2fc6140f022bbcd6..757a825eeef1fa3730fdafd46081b33af69f6fca 100644
--- a/docs/c-api/mqtt.h/mg_mqtt_ping.md
+++ b/docs/c-api/mqtt.h/mg_mqtt_ping.md
@@ -6,5 +6,5 @@ signature: |
void mg_mqtt_ping(struct mg_connection *nc);
---
-Send a PINGREQ command.
+Sends a PINGREQ command.
diff --git a/docs/c-api/mqtt.h/mg_mqtt_pong.md b/docs/c-api/mqtt.h/mg_mqtt_pong.md
index da353b5729f59598235ccc9ce3a1ce04303feaba..c79253e3ec7255d0ee9be54a73d38a30d9db5bd3 100644
--- a/docs/c-api/mqtt.h/mg_mqtt_pong.md
+++ b/docs/c-api/mqtt.h/mg_mqtt_pong.md
@@ -6,5 +6,5 @@ signature: |
void mg_mqtt_pong(struct mg_connection *nc);
---
-Send a PINGRESP command.
+Sends a PINGRESP command.
diff --git a/docs/c-api/mqtt.h/mg_mqtt_puback.md b/docs/c-api/mqtt.h/mg_mqtt_puback.md
index aad96f66931242df02f572f0c7e19b68dee30973..a29a352d29f889660573c20c4e74a8eef60ebeba 100644
--- a/docs/c-api/mqtt.h/mg_mqtt_puback.md
+++ b/docs/c-api/mqtt.h/mg_mqtt_puback.md
@@ -6,5 +6,5 @@ signature: |
void mg_mqtt_puback(struct mg_connection *nc, uint16_t message_id);
---
-Send a PUBACK command with a given `message_id`.
+Sends a PUBACK command with a given `message_id`.
diff --git a/docs/c-api/mqtt.h/mg_mqtt_pubcomp.md b/docs/c-api/mqtt.h/mg_mqtt_pubcomp.md
index aab320f611ab0a4c06ec4dd5b45c145ef6918826..bc3228ca9b0268fa29e0d171078ca0d8d97278f1 100644
--- a/docs/c-api/mqtt.h/mg_mqtt_pubcomp.md
+++ b/docs/c-api/mqtt.h/mg_mqtt_pubcomp.md
@@ -6,5 +6,5 @@ signature: |
void mg_mqtt_pubcomp(struct mg_connection *nc, uint16_t message_id);
---
-Send a PUBCOMP command with a given `message_id`.
+Sends a PUBCOMP command with a given `message_id`.
diff --git a/docs/c-api/mqtt.h/mg_mqtt_publish.md b/docs/c-api/mqtt.h/mg_mqtt_publish.md
index 8b28c57ba1e221f3ad5959eda455a03916012b7d..b2a7b013b19f833a6f59a07723d65e7841fc7269 100644
--- a/docs/c-api/mqtt.h/mg_mqtt_publish.md
+++ b/docs/c-api/mqtt.h/mg_mqtt_publish.md
@@ -8,5 +8,5 @@ signature: |
size_t len);
---
-Publish a message to a given topic.
+Publishes a message to a given topic.
diff --git a/docs/c-api/mqtt.h/mg_mqtt_pubrec.md b/docs/c-api/mqtt.h/mg_mqtt_pubrec.md
index e5173f771cb8e6ea4ebdcaea0dc395b916729463..16cdc7d0d820c708a5fb05fbfd2cfe3080fdca3a 100644
--- a/docs/c-api/mqtt.h/mg_mqtt_pubrec.md
+++ b/docs/c-api/mqtt.h/mg_mqtt_pubrec.md
@@ -6,5 +6,5 @@ signature: |
void mg_mqtt_pubrec(struct mg_connection *nc, uint16_t message_id);
---
-Send a PUBREC command with a given `message_id`.
+Sends a PUBREC command with a given `message_id`.
diff --git a/docs/c-api/mqtt.h/mg_mqtt_pubrel.md b/docs/c-api/mqtt.h/mg_mqtt_pubrel.md
index 899e8b9db5bd2c162588779cf8ec587dc4a650ae..18a6c58133400c6967739a1adb26f35e7da1aa49 100644
--- a/docs/c-api/mqtt.h/mg_mqtt_pubrel.md
+++ b/docs/c-api/mqtt.h/mg_mqtt_pubrel.md
@@ -6,5 +6,5 @@ signature: |
void mg_mqtt_pubrel(struct mg_connection *nc, uint16_t message_id);
---
-Send a PUBREL command with a given `message_id`.
+Sends a PUBREL command with a given `message_id`.
diff --git a/docs/c-api/mqtt.h/mg_mqtt_suback.md b/docs/c-api/mqtt.h/mg_mqtt_suback.md
index 943fd65e38b582b5a039806efe0911dc90db0bfd..55cf5e3a2eb29cd56413705d54e650170f167df8 100644
--- a/docs/c-api/mqtt.h/mg_mqtt_suback.md
+++ b/docs/c-api/mqtt.h/mg_mqtt_suback.md
@@ -7,6 +7,6 @@ signature: |
uint16_t message_id);
---
-Send a SUBACK command with a given `message_id`
+Sends a SUBACK command with a given `message_id`
and a sequence of granted QoSs.
diff --git a/docs/c-api/mqtt.h/mg_mqtt_subscribe.md b/docs/c-api/mqtt.h/mg_mqtt_subscribe.md
index 0978b071a8189c392d15a81b328c40957a7189ca..0168db410e457235b976efe9808146f136442d00 100644
--- a/docs/c-api/mqtt.h/mg_mqtt_subscribe.md
+++ b/docs/c-api/mqtt.h/mg_mqtt_subscribe.md
@@ -8,5 +8,5 @@ signature: |
size_t topics_len, uint16_t message_id);
---
-Subscribe to a bunch of topics.
+Subscribes to a bunch of topics.
diff --git a/docs/c-api/mqtt.h/mg_mqtt_unsuback.md b/docs/c-api/mqtt.h/mg_mqtt_unsuback.md
index e3f6e6ea4a2105083d49b12ee3733ccc6cd6e947..a86fffc51a1d680037b073d5a76eaabc04dc27ba 100644
--- a/docs/c-api/mqtt.h/mg_mqtt_unsuback.md
+++ b/docs/c-api/mqtt.h/mg_mqtt_unsuback.md
@@ -6,5 +6,5 @@ signature: |
void mg_mqtt_unsuback(struct mg_connection *nc, uint16_t message_id);
---
-Send a UNSUBACK command with a given `message_id`.
+Sends a UNSUBACK command with a given `message_id`.
diff --git a/docs/c-api/mqtt.h/mg_mqtt_unsubscribe.md b/docs/c-api/mqtt.h/mg_mqtt_unsubscribe.md
index 73a283e3e5d9a9c0e0da3b0d6eaa2f91425ddf9b..b4c1f783b470dc0294345cb53fea32b30d9b5b2f 100644
--- a/docs/c-api/mqtt.h/mg_mqtt_unsubscribe.md
+++ b/docs/c-api/mqtt.h/mg_mqtt_unsubscribe.md
@@ -7,5 +7,5 @@ signature: |
size_t topics_len, uint16_t message_id);
---
-Unsubscribe from a bunch of topics.
+Unsubscribes from a bunch of topics.
diff --git a/docs/c-api/mqtt.h/mg_send_mqtt_handshake.md b/docs/c-api/mqtt.h/mg_send_mqtt_handshake.md
index 1e903f90c9cd17ca81c047918e8ad3754350b131..0e75c4e31a506e2b5fc3078824f57a3faeaac96f 100644
--- a/docs/c-api/mqtt.h/mg_send_mqtt_handshake.md
+++ b/docs/c-api/mqtt.h/mg_send_mqtt_handshake.md
@@ -6,5 +6,5 @@ signature: |
void mg_send_mqtt_handshake(struct mg_connection *nc, const char *client_id);
---
-Send MQTT handshake.
+Sends an MQTT handshake.
diff --git a/docs/c-api/mqtt.h/mg_send_mqtt_handshake_opt.md b/docs/c-api/mqtt.h/mg_send_mqtt_handshake_opt.md
index c1d3fd4c2b4b7cdd782f9e1bcd934b7682b976b3..2c7a93ca6068dfe7dc7ab4ac224972b09b055308 100644
--- a/docs/c-api/mqtt.h/mg_send_mqtt_handshake_opt.md
+++ b/docs/c-api/mqtt.h/mg_send_mqtt_handshake_opt.md
@@ -7,5 +7,5 @@ signature: |
struct mg_send_mqtt_handshake_opts);
---
-Send MQTT handshake with optional parameters.
+Sends an MQTT handshake with optional parameters.
diff --git a/docs/c-api/mqtt.h/mg_set_protocol_mqtt.md b/docs/c-api/mqtt.h/mg_set_protocol_mqtt.md
index a559eae825adacede4ce23bfc9ea2616c5b1b991..8c65d385a04556501b21afea65d93d594f4af420 100644
--- a/docs/c-api/mqtt.h/mg_set_protocol_mqtt.md
+++ b/docs/c-api/mqtt.h/mg_set_protocol_mqtt.md
@@ -6,7 +6,7 @@ signature: |
void mg_set_protocol_mqtt(struct mg_connection *nc);
---
-Attach built-in MQTT event handler to the given connection.
+Attaches a built-in MQTT event handler to the given connection.
The user-defined event handler will receive following extra events:
diff --git a/docs/c-api/net.h/mg_add_sock.md b/docs/c-api/net.h/mg_add_sock.md
index 268dc33444525c6df0cd99987a20ecc54ab0e4a5..511ae84100b786819ba93153a00e67e9b8de98ef 100644
--- a/docs/c-api/net.h/mg_add_sock.md
+++ b/docs/c-api/net.h/mg_add_sock.md
@@ -6,8 +6,8 @@ signature: |
struct mg_connection *mg_add_sock(struct mg_mgr *, sock_t, mg_event_handler_t);
---
-Create a connection, associate it with the given socket and event handler,
-and add it to the manager.
+Creates a connection, associates it with the given socket and event handler
+and adds it to the manager.
For more options see the `mg_add_sock_opt` variant.
diff --git a/docs/c-api/net.h/mg_add_sock_opt.md b/docs/c-api/net.h/mg_add_sock_opt.md
index 9a94aee7f037a3b7b800dc7a4b9868be977ee7a1..678a91cbb8fdfa55a295f88b11d84f6ef4ce6ac5 100644
--- a/docs/c-api/net.h/mg_add_sock_opt.md
+++ b/docs/c-api/net.h/mg_add_sock_opt.md
@@ -8,8 +8,8 @@ signature: |
struct mg_add_sock_opts);
---
-Create a connection, associate it with the given socket and event handler,
-and add to the manager.
+Creates a connection, associates it with the given socket and event handler
+and adds to the manager.
See the `mg_add_sock_opts` structure for a description of the options.
diff --git a/docs/c-api/net.h/mg_bind.md b/docs/c-api/net.h/mg_bind.md
index b6106219b268156becb6eabb5aeb2f3eead4d65a..800bba9547f2bb7d7341a64d9fd455bbeacb6f5b 100644
--- a/docs/c-api/net.h/mg_bind.md
+++ b/docs/c-api/net.h/mg_bind.md
@@ -7,7 +7,7 @@ signature: |
mg_event_handler_t);
---
-Create listening connection.
+Creates a listening connection.
See `mg_bind_opt` for full documentation.
diff --git a/docs/c-api/net.h/mg_bind_opt.md b/docs/c-api/net.h/mg_bind_opt.md
index 4fb514bf783b6e372edc78945ae39a6c34e1cc36..a9cbf953e0d248bcb3cbc62dc6c376c9e9e6f884 100644
--- a/docs/c-api/net.h/mg_bind_opt.md
+++ b/docs/c-api/net.h/mg_bind_opt.md
@@ -8,19 +8,20 @@ signature: |
struct mg_bind_opts opts);
---
-Create listening connection.
+Creates a listening connection.
-`address` parameter tells which address to bind to. It's format is the same
-as for the `mg_connect()` call, where `HOST` part is optional. `address`
-can be just a port number, e.g. `:8000`. To bind to a specific interface,
-an IP address can be specified, e.g. `1.2.3.4:8000`. By default, a TCP
-connection is created. To create UDP connection, prepend `udp://` prefix,
-e.g. `udp://:8000`. To summarize, `address` paramer has following format:
-`[PROTO://][IP_ADDRESS]:PORT`, where `PROTO` could be `tcp` or `udp`.
+The `address` parameter specifies which address to bind to. It's format is
+the same as for the `mg_connect()` call, where `HOST` part is optional.
+`address` can be just a port number, e.g. `:8000`. To bind to a specific
+interface, an IP address can be specified, e.g. `1.2.3.4:8000`. By default,
+a TCP connection is created. To create UDP connection, prepend `udp://`
+prefix, e.g. `udp://:8000`. To summarize, `address` paramer has following
+format: `[PROTO://][IP_ADDRESS]:PORT`, where `PROTO` could be `tcp` or
+`udp`.
See the `mg_bind_opts` structure for a description of the optional
parameters.
-Return a new listening connection, or `NULL` on error.
-NOTE: Connection remains owned by the manager, do not free().
+Returns a new listening connection or `NULL` on error.
+NOTE: The connection remains owned by the manager, do not free().
diff --git a/docs/c-api/net.h/mg_broadcast.md b/docs/c-api/net.h/mg_broadcast.md
index 94fceb8f0a6526e8b4d62ed56fb0dcdd7452040e..4eda7f3cd833e4049017d0524e99dee84444a361 100644
--- a/docs/c-api/net.h/mg_broadcast.md
+++ b/docs/c-api/net.h/mg_broadcast.md
@@ -6,14 +6,14 @@ signature: |
void mg_broadcast(struct mg_mgr *, mg_event_handler_t func, void *, size_t);
---
-Pass a message of a given length to all connections.
+Passes a message of a given length to all connections.
Must be called from a thread that does NOT call `mg_mgr_poll()`.
Note that `mg_broadcast()` is the only function
that can be, and must be, called from a different (non-IO) thread.
`func` callback function will be called by the IO thread for each
-connection. When called, event would be `MG_EV_POLL`, and message will
-be passed as `ev_data` pointer. Maximum message size is capped
+connection. When called, the event will be `MG_EV_POLL`, and a message will
+be passed as the `ev_data` pointer. Maximum message size is capped
by `MG_CTL_MSG_MESSAGE_SIZE` which is set to 8192 bytes.
diff --git a/docs/c-api/net.h/mg_check_ip_acl.md b/docs/c-api/net.h/mg_check_ip_acl.md
index 957a684fbe3b0afd0139b28c695241d8d9a401f4..e3087e2b2f2c060dfc29f5be4e84ec0ba03b5fe3 100644
--- a/docs/c-api/net.h/mg_check_ip_acl.md
+++ b/docs/c-api/net.h/mg_check_ip_acl.md
@@ -13,15 +13,15 @@ Verify given IP address against the ACL.
Each subnet is
prepended by either a - or a + sign. A plus sign means allow, where a
minus sign means deny. If a subnet mask is omitted, such as `-1.2.3.4`,
-this means to deny only that single IP address.
+it means that only that single IP address is denied.
Subnet masks may vary from 0 to 32, inclusive. The default setting
-is to allow all accesses. On each request the full list is traversed,
+is to allow all access. On each request the full list is traversed,
and the last match wins. Example:
`-0.0.0.0/0,+192.168/16` - deny all acccesses, only allow 192.168/16 subnet
-To learn more about subnet masks, see the
-link:https://en.wikipedia.org/wiki/Subnetwork[Wikipedia page on Subnetwork]
+To learn more about subnet masks, see this
+link:https://en.wikipedia.org/wiki/Subnetwork[Wikipedia page on Subnetwork].
-Return -1 if ACL is malformed, 0 if address is disallowed, 1 if allowed.
+Returns -1 if ACL is malformed, 0 if address is disallowed, 1 if allowed.
diff --git a/docs/c-api/net.h/mg_connect.md b/docs/c-api/net.h/mg_connect.md
index 388196e31030dc4583caf6dee5b50eda4e34a568..bbacd8f4c9faac91271151c4a9a0bfbf859733f0 100644
--- a/docs/c-api/net.h/mg_connect.md
+++ b/docs/c-api/net.h/mg_connect.md
@@ -7,7 +7,7 @@ signature: |
mg_event_handler_t handler);
---
-Connect to a remote host.
+Connects to a remote host.
See `mg_connect_opt()` for full documentation.
diff --git a/docs/c-api/net.h/mg_connect_opt.md b/docs/c-api/net.h/mg_connect_opt.md
index d169ded105d68411572e9210e832037587eed474..de7e71392fdc279bea3001376481b2faf2863a30 100644
--- a/docs/c-api/net.h/mg_connect_opt.md
+++ b/docs/c-api/net.h/mg_connect_opt.md
@@ -8,11 +8,11 @@ signature: |
struct mg_connect_opts opts);
---
-Connect to a remote host.
+Connects to a remote host.
-`address` format is `[PROTO://]HOST:PORT`. `PROTO` could be `tcp` or `udp`.
-`HOST` could be an IP address,
-IPv6 address (if Mongoose is compiled with `-DMG_ENABLE_IPV6`), or a host
+The `address` format is `[PROTO://]HOST:PORT`. `PROTO` could be `tcp` or
+`udp`. `HOST` could be an IP address,
+IPv6 address (if Mongoose is compiled with `-DMG_ENABLE_IPV6`) or a host
name. If `HOST` is a name, Mongoose will resolve it asynchronously. Examples
of valid addresses: `google.com:80`, `udp://1.2.3.4:53`, `10.0.0.1:443`,
`[::1]:80`
@@ -20,18 +20,18 @@ of valid addresses: `google.com:80`, `udp://1.2.3.4:53`, `10.0.0.1:443`,
See the `mg_connect_opts` structure for a description of the optional
parameters.
-Returns a new outbound connection, or `NULL` on error.
+Returns a new outbound connection or `NULL` on error.
-NOTE: Connection remains owned by the manager, do not free().
+NOTE: The connection remains owned by the manager, do not free().
-NOTE: To enable IPv6 addresses, `-DMG_ENABLE_IPV6` should be specified
+NOTE: To enable IPv6 addresses `-DMG_ENABLE_IPV6` should be specified
in the compilation flags.
-NOTE: New connection will receive `MG_EV_CONNECT` as it's first event
-which will report connect success status.
-If asynchronous resolution fail, or `connect()` syscall fail for whatever
-reason (e.g. with `ECONNREFUSED` or `ENETUNREACH`), then `MG_EV_CONNECT`
-event report failure. Code example below:
+NOTE: The new connection will receive `MG_EV_CONNECT` as its first event
+which will report the connect success status.
+If the asynchronous resolution fails or the `connect()` syscall fails for
+whatever reason (e.g. with `ECONNREFUSED` or `ENETUNREACH`), then
+`MG_EV_CONNECT` event will report failure. Code example below:
```c
static void ev_handler(struct mg_connection *nc, int ev, void *ev_data) {
diff --git a/docs/c-api/net.h/mg_enable_javascript.md b/docs/c-api/net.h/mg_enable_javascript.md
index cb2753866a677a554e9d084db7a0bcc67e17c5a3..763151e02bc46ff18cc856cc897c5f5d4b844601 100644
--- a/docs/c-api/net.h/mg_enable_javascript.md
+++ b/docs/c-api/net.h/mg_enable_javascript.md
@@ -7,8 +7,8 @@ signature: |
const char *init_js_file_name);
---
-Enable server-side JavaScript scripting.
-Requires `-DMG_ENABLE_JAVASCRIPT` compilation flag, and V7 engine sources.
-v7 instance must not be destroyed during manager's lifetime.
-Return V7 error.
+Enables server-side JavaScript scripting.
+Requires a `-DMG_ENABLE_JAVASCRIPT` compilation flag and V7 engine sources.
+V7 instance must not be destroyed during manager's lifetime.
+Returns a V7 error.
diff --git a/docs/c-api/net.h/mg_enable_multithreading.md b/docs/c-api/net.h/mg_enable_multithreading.md
index 3498e4de3d5df370331d043f0b99131f2df86aca..e45fd3a1b8113d65c2c3af42a2fb3b81f52b1138 100644
--- a/docs/c-api/net.h/mg_enable_multithreading.md
+++ b/docs/c-api/net.h/mg_enable_multithreading.md
@@ -6,9 +6,9 @@ signature: |
void mg_enable_multithreading(struct mg_connection *nc);
---
-Enable multi-threaded handling for the given listening connection `nc`.
+Enables multi-threaded handling for the given listening connection `nc`.
For each accepted connection, Mongoose will create a separate thread
-and run event handler in that thread. Thus, if an event hanler is doing
-a blocking call or some long computation, that will not slow down
+and run an event handler in that thread. Thus, if an event handler is doing
+a blocking call or some long computation, it will not slow down
other connections.
diff --git a/docs/c-api/net.h/mg_event_handler_t.md b/docs/c-api/net.h/mg_event_handler_t.md
index af94bb0e1887a1e05fcd29f9779e7c972dd07898..f436d667dded93d5f9e4ede15e457bf549d48298 100644
--- a/docs/c-api/net.h/mg_event_handler_t.md
+++ b/docs/c-api/net.h/mg_event_handler_t.md
@@ -7,5 +7,5 @@ signature: |
---
Callback function (event handler) prototype. Must be defined by the user.
-Mongoose calls the event handler, passing events defined below.
+Mongoose calls the event handler, passing the events defined below.
diff --git a/docs/c-api/net.h/mg_mgr_free.md b/docs/c-api/net.h/mg_mgr_free.md
index 07ca25d3c25b6b936b9cff4b82ab8b0042735829..d2df34e4c268278da83abc9d4c2b725aea297943 100644
--- a/docs/c-api/net.h/mg_mgr_free.md
+++ b/docs/c-api/net.h/mg_mgr_free.md
@@ -6,7 +6,7 @@ signature: |
void mg_mgr_free(struct mg_mgr *);
---
-De-initializes Mongoose manager.
+De-initialises Mongoose manager.
-Close and deallocate all active connections.
+Closes and deallocates all active connections.
diff --git a/docs/c-api/net.h/mg_mgr_init.md b/docs/c-api/net.h/mg_mgr_init.md
index b59506bdf2a2456e75faace064b937c350f3a997..1e44bf50225d2339e9056f36275a9ef708cee28d 100644
--- a/docs/c-api/net.h/mg_mgr_init.md
+++ b/docs/c-api/net.h/mg_mgr_init.md
@@ -6,10 +6,10 @@ signature: |
void mg_mgr_init(struct mg_mgr *mgr, void *user_data);
---
-Initialize Mongoose manager. Side effect: ignores SIGPIPE signal.
-`mgr->user_data` field will be initialized with `user_data` parameter.
-That is an arbitrary pointer, where user code can associate some data
+Initialise Mongoose manager. Side effect: ignores SIGPIPE signal.
+`mgr->user_data` field will be initialised with a `user_data` parameter.
+That is an arbitrary pointer, where the user code can associate some data
with the particular Mongoose manager. For example, a C++ wrapper class
-could be written, in which case `user_data` can hold a pointer to the
+could be written in which case `user_data` can hold a pointer to the
class instance.
diff --git a/docs/c-api/net.h/mg_mgr_poll.md b/docs/c-api/net.h/mg_mgr_poll.md
index f25c759560f17dc47e2e72d893fcedeb07e62352..b70c31b6db0229534694d1a8e31a8328a2e2f723 100644
--- a/docs/c-api/net.h/mg_mgr_poll.md
+++ b/docs/c-api/net.h/mg_mgr_poll.md
@@ -6,10 +6,10 @@ signature: |
time_t mg_mgr_poll(struct mg_mgr *, int milli);
---
-This function performs the actual IO, and must be called in a loop
-(an event loop). Returns the current timestamp.
+This function performs the actual IO and must be called in a loop
+(an event loop). It returns the current timestamp.
`milli` is the maximum number of milliseconds to sleep.
-`mg_mgr_poll()` checks all connection for IO readiness. If at least one
-of the connections is IO-ready, `mg_mgr_poll()` triggers respective
+`mg_mgr_poll()` checks all connections for IO readiness. If at least one
+of the connections is IO-ready, `mg_mgr_poll()` triggers the respective
event handlers and returns.
diff --git a/docs/c-api/net.h/mg_next.md b/docs/c-api/net.h/mg_next.md
index fc817262d0b1217309347b75431d4da66dda3fe6..fcd5e1d17b92348206810fcbaba11c444dbdaa92 100644
--- a/docs/c-api/net.h/mg_next.md
+++ b/docs/c-api/net.h/mg_next.md
@@ -6,10 +6,10 @@ signature: |
struct mg_connection *mg_next(struct mg_mgr *, struct mg_connection *);
---
-Iterate over all active connections.
+Iterates over all active connections.
-Returns next connection from the list
-of active connections, or `NULL` if there is no more connections. Below
+Returns the next connection from the list
+of active connections or `NULL` if there are no more connections. Below
is the iteration idiom:
```c
diff --git a/docs/c-api/net.h/mg_printf.md b/docs/c-api/net.h/mg_printf.md
index 281fb4fd50dcc73ed1e1cefd710ee9bfc5437706..2448235f7c280adbe461329a8dfb414591924c4d 100644
--- a/docs/c-api/net.h/mg_printf.md
+++ b/docs/c-api/net.h/mg_printf.md
@@ -6,7 +6,7 @@ signature: |
int mg_printf(struct mg_connection *, const char *fmt, ...);
---
-Send `printf`-style formatted data to the connection.
+Sends `printf`-style formatted data to the connection.
See `mg_send` for more details on send semantics.
diff --git a/docs/c-api/net.h/mg_send.md b/docs/c-api/net.h/mg_send.md
index e1aed3e031521d5b0ef2f347aaad6745cb0fbea5..c6963a0d606cf4fb34955560bc5a2045a6cc23bc 100644
--- a/docs/c-api/net.h/mg_send.md
+++ b/docs/c-api/net.h/mg_send.md
@@ -6,7 +6,7 @@ signature: |
void mg_send(struct mg_connection *, const void *buf, int len);
---
-Send data to the connection.
+Sends data to the connection.
Note that sending functions do not actually push data to the socket.
They just append data to the output buffer. MG_EV_SEND will be delivered when
diff --git a/docs/c-api/net.h/mg_set_ssl.md b/docs/c-api/net.h/mg_set_ssl.md
index d2b3b654b0c1549c69c2221468709510f88d33c0..35d12d399159be6e706f125217043a58a5b1ab5d 100644
--- a/docs/c-api/net.h/mg_set_ssl.md
+++ b/docs/c-api/net.h/mg_set_ssl.md
@@ -7,15 +7,16 @@ signature: |
const char *ca_cert);
---
-Note: This function is deprecated, please use SSL options in mg_connect_opt.
+Note: This function is deprecated. Please, use SSL options in
+mg_connect_opt.
-Enable SSL for a given connection.
-`cert` is a server certificate file name for a listening connection,
+Enables SSL for a given connection.
+`cert` is a server certificate file name for a listening connection
or a client certificate file name for an outgoing connection.
-Certificate files must be in PEM format. Server certificate file
+The certificate files must be in PEM format. The server certificate file
must contain a certificate, concatenated with a private key, optionally
concatenated with DH parameters.
-`ca_cert` is a CA certificate, or NULL if peer verification is not
+`ca_cert` is a CA certificate or NULL if peer verification is not
required.
-Return: NULL on success, or error message on error.
+Return: NULL on success or error message on error.
diff --git a/docs/c-api/net.h/mg_set_timer.md b/docs/c-api/net.h/mg_set_timer.md
index e559c26b26d1ce1d199a8e78e6a54199e5ea36d3..0b089206512d94e143f82e15660f142fa257a95c 100644
--- a/docs/c-api/net.h/mg_set_timer.md
+++ b/docs/c-api/net.h/mg_set_timer.md
@@ -6,12 +6,12 @@ signature: |
double mg_set_timer(struct mg_connection *c, double timestamp);
---
-Schedule MG_EV_TIMER event to be delivered at `timestamp` time.
-`timestamp` is a UNIX time (a number of seconds since Epoch). It is
+Schedules an MG_EV_TIMER event to be delivered at `timestamp` time.
+`timestamp` is UNIX time (the number of seconds since Epoch). It is
`double` instead of `time_t` to allow for sub-second precision.
-Return the old timer value.
+Returns the old timer value.
-Example: set connect timeout to 1.5 seconds:
+Example: set the connect timeout to 1.5 seconds:
```
c = mg_connect(&mgr, "cesanta.com", ev_handler);
diff --git a/docs/c-api/net.h/mg_socketpair.md b/docs/c-api/net.h/mg_socketpair.md
index 1509c0f3a18ee5ed89c8bf1b3bc549b3b3264cd7..bd36cbce75eb861b9accfd3fd0fe272fac0cfd83 100644
--- a/docs/c-api/net.h/mg_socketpair.md
+++ b/docs/c-api/net.h/mg_socketpair.md
@@ -6,7 +6,7 @@ signature: |
int mg_socketpair(sock_t[2], int sock_type);
---
-Create a socket pair.
+Creates a socket pair.
`sock_type` can be either `SOCK_STREAM` or `SOCK_DGRAM`.
-Return 0 on failure, 1 on success.
+Returns 0 on failure and 1 on success.
diff --git a/docs/c-api/util.h/mg_avprintf.md b/docs/c-api/util.h/mg_avprintf.md
index efc424d004ea20e2c2e2a974cfb5d72f23e6c085..9a70d8400685982c3b7dd3bdcf99391d4afd43ea 100644
--- a/docs/c-api/util.h/mg_avprintf.md
+++ b/docs/c-api/util.h/mg_avprintf.md
@@ -6,9 +6,9 @@ signature: |
int mg_avprintf(char **buf, size_t size, const char *fmt, va_list ap);
---
-Print message to buffer. If buffer is large enough to hold the message,
-return buffer. If buffer is to small, allocate large enough buffer on heap,
-and return allocated buffer.
+Prints message to the buffer. If the buffer is large enough to hold the
+message, it returns buffer. If buffer is to small, it allocates a large
+enough buffer on heap and returns allocated buffer.
This is a supposed use case:
char buf[5], *p = buf;
diff --git a/docs/c-api/util.h/mg_base64_decode.md b/docs/c-api/util.h/mg_base64_decode.md
index 3fa77428fdf8dcdb0f86e1d4f339f62834e99ebe..92f7c10bfcf836abf6f3df41822fe3c70c469705 100644
--- a/docs/c-api/util.h/mg_base64_decode.md
+++ b/docs/c-api/util.h/mg_base64_decode.md
@@ -6,11 +6,12 @@ signature: |
int mg_base64_decode(const unsigned char *s, int len, char *dst);
---
-Decode base64-encoded string `s`, `len` into the destination `dst`.
-Destination has to have enough space to hold decoded buffer.
-Decoding stops either when all string has been decoded, or invalid
+Decodes base64-encoded string `s`, `len` into the destination `dst`.
+The destination has to have enough space to hold the decoded buffer.
+Decoding stops either when all strings have been decoded or invalid an
character appeared.
Destination is '\0'-terminated.
-Return number of decoded characters. On success, that should be equal to
-`len`. On error (invalid character) the return value is smaller then `len`.
+Returns the number of decoded characters. On success, that should be equal
+to `len`. On error (invalid character) the return value is smaller then
+`len`.
diff --git a/docs/c-api/util.h/mg_conn_addr_to_str.md b/docs/c-api/util.h/mg_conn_addr_to_str.md
index f17bfb70f48270cd5a4ac989e1ff861235ece58b..e623734fbf0b5286de40fbe6c20dbb1d548c7c04 100644
--- a/docs/c-api/util.h/mg_conn_addr_to_str.md
+++ b/docs/c-api/util.h/mg_conn_addr_to_str.md
@@ -7,9 +7,9 @@ signature: |
int flags);
---
-Convert connection's local or remote address into string.
+Converts a connection's local or remote address into string.
-The `flags` parameter is a bit mask that controls the behavior,
+The `flags` parameter is a bit mask that controls the behaviour,
see `MG_SOCK_STRINGIFY_*` definitions.
- MG_SOCK_STRINGIFY_IP - print IP address
diff --git a/docs/c-api/util.h/mg_fopen.md b/docs/c-api/util.h/mg_fopen.md
index 3446670c28435e783fe0f01ab4c9eb9e2009238a..3cb8568a06fba33378dae08cbd1ba80a2df1d81e 100644
--- a/docs/c-api/util.h/mg_fopen.md
+++ b/docs/c-api/util.h/mg_fopen.md
@@ -6,7 +6,7 @@ signature: |
FILE *mg_fopen(const char *path, const char *mode);
---
-Open the given file and return a file stream.
+Opens the given file and returns a file stream.
`path` and `mode` should be UTF8 encoded.
diff --git a/docs/c-api/util.h/mg_hexdump.md b/docs/c-api/util.h/mg_hexdump.md
index ed02068aa82a1bd48c1cc70cd6c9f63333a35871..c8376bf62105231cb7d39c9b1103426c480395f9 100644
--- a/docs/c-api/util.h/mg_hexdump.md
+++ b/docs/c-api/util.h/mg_hexdump.md
@@ -6,10 +6,10 @@ signature: |
int mg_hexdump(const void *buf, int len, char *dst, int dst_len);
---
-Generates human-readable hexdump of memory chunk.
+Generates a human-readable hexdump of memory chunk.
Takes a memory buffer `buf` of length `len` and creates a hex dump of that
-buffer in `dst`. Generated output is a-la hexdump(1).
-Return length of generated string, excluding terminating `\0`. If returned
-length is bigger than `dst_len`, overflow bytes are discarded.
+buffer in `dst`. The generated output is a-la hexdump(1).
+Returns the length of generated string, excluding terminating `\0`. If
+returned length is bigger than `dst_len`, the overflow bytes are discarded.
diff --git a/docs/c-api/util.h/mg_hexdump_connection.md b/docs/c-api/util.h/mg_hexdump_connection.md
index 2e6d520d7adaf3f47718558305647fd7e4e1af0c..03d8a6b2d728189545475700c4495a1e5828de4b 100644
--- a/docs/c-api/util.h/mg_hexdump_connection.md
+++ b/docs/c-api/util.h/mg_hexdump_connection.md
@@ -7,9 +7,9 @@ signature: |
const void *buf, int num_bytes, int ev);
---
-Generates human-readable hexdump of the data sent or received by connection.
-`path` is a file name where hexdump should be written. `num_bytes` is
-a number of bytes sent/received. `ev` is one of the `MG_*` events sent to
-an event handler. This function is supposed to be called from the
-event handler.
+Generates human-readable hexdump of the data sent or received by the
+connection. `path` is a file name where hexdump should be written.
+`num_bytes` is a number of bytes sent/received. `ev` is one of the `MG_*`
+events sent to an event handler. This function is supposed to be called from
+the event handler.
diff --git a/docs/c-api/util.h/mg_is_big_endian.md b/docs/c-api/util.h/mg_is_big_endian.md
index ba33f4d7dfe024dc4116665032f71f0d6c355d86..4cd54da7ecf3bd282977f85727f0b351a43be318 100644
--- a/docs/c-api/util.h/mg_is_big_endian.md
+++ b/docs/c-api/util.h/mg_is_big_endian.md
@@ -6,5 +6,5 @@ signature: |
int mg_is_big_endian(void);
---
-Return true if target platform is big endian.
+Returns true if target platform is big endian.
diff --git a/docs/c-api/util.h/mg_match_prefix.md b/docs/c-api/util.h/mg_match_prefix.md
index 17da2ea7aadc63d2c706f2a6fc6885663ea0c7e6..15ddc9ef1fc17e80f343bec5b6fbeb665f377ad2 100644
--- a/docs/c-api/util.h/mg_match_prefix.md
+++ b/docs/c-api/util.h/mg_match_prefix.md
@@ -6,7 +6,9 @@ signature: |
int mg_match_prefix(const char *pattern, int pattern_len, const char *str);
---
-Match 0-terminated string (mg_match_prefix) or string with given length
+Matches 0-terminated string (mg_match_prefix) or string with given length
mg_match_prefix_n against a glob pattern.
-Match is case-insensitive. Return number of bytes matched, or -1 if no match.
+
+Match is case-insensitive. Returns number of bytes matched, or -1 if no
+match.
diff --git a/docs/c-api/util.h/mg_next_comma_list_entry.md b/docs/c-api/util.h/mg_next_comma_list_entry.md
index e82d06095e147b487d520c13a8f1f585fab0ee4c..a96103936f5463494dfd5e0dda46da5354f1dc0d 100644
--- a/docs/c-api/util.h/mg_next_comma_list_entry.md
+++ b/docs/c-api/util.h/mg_next_comma_list_entry.md
@@ -8,12 +8,12 @@ signature: |
---
A helper function for traversing a comma separated list of values.
-It returns a list pointer shifted to the next value, or NULL if the end
+It returns a list pointer shifted to the next value or NULL if the end
of the list found.
-Value is stored in val vector. If value has form "x=y", then eq_val
-vector is initialized to point to the "y" part, and val vector length
+The value is stored in a val vector. If the value has a form "x=y", then
+eq_val vector is initialised to point to the "y" part, and val vector length
is adjusted to point only to "x".
-If list is just a comma separated list of entries, like "aa,bb,cc" then
+If the list is just a comma separated list of entries, like "aa,bb,cc" then
`eq_val` will contain zero-length string.
The purpose of this function is to parse comma separated string without
diff --git a/docs/c-api/util.h/mg_open.md b/docs/c-api/util.h/mg_open.md
index 385446709dd3854dd9738badb2ff49c8b88c20e0..aaa8e56eaf8b664050dc434fcc899baca96c46a0 100644
--- a/docs/c-api/util.h/mg_open.md
+++ b/docs/c-api/util.h/mg_open.md
@@ -6,7 +6,7 @@ signature: |
int mg_open(const char *path, int flag, int mode);
---
-Open the given file and return a file stream.
+Opens the given file and returns a file stream.
`path` should be UTF8 encoded.
diff --git a/docs/c-api/util.h/mg_skip.md b/docs/c-api/util.h/mg_skip.md
index 858dc1d77836ef9242ecf16c18e4da385099b134..cc7b2fd14bb1c3ea6b057f3e7aa15dadc8d3a342 100644
--- a/docs/c-api/util.h/mg_skip.md
+++ b/docs/c-api/util.h/mg_skip.md
@@ -7,11 +7,11 @@ signature: |
const char *delimiters, struct mg_str *v);
---
-Fetch substring from input string `s`, `end` into `v`.
+Fetches substring from input string `s`, `end` into `v`.
Skips initial delimiter characters. Records first non-delimiter character
-as the beginning of substring `v`. Then scans the rest of the string
+at the beginning of substring `v`. Then scans the rest of the string
until a delimiter character or end-of-string is found.
`delimiters` is a 0-terminated string containing delimiter characters.
Either one of `delimiters` or `end_string` terminates the search.
-Return an `s` pointer, advanced forward where parsing stopped.
+Returns an `s` pointer, advanced forward where parsing has stopped.
diff --git a/docs/c-api/util.h/mg_sock_addr_to_str.md b/docs/c-api/util.h/mg_sock_addr_to_str.md
index 0563630b126bd2de48635d97daab9780952ab8e0..3502e135e44da7e64a51d0b2d6b9fbab944fe234 100644
--- a/docs/c-api/util.h/mg_sock_addr_to_str.md
+++ b/docs/c-api/util.h/mg_sock_addr_to_str.md
@@ -7,7 +7,7 @@ signature: |
int flags);
---
-Convert socket's address into string.
+Convert the socket's address into string.
`flags` is MG_SOCK_STRINGIFY_IP and/or MG_SOCK_STRINGIFY_PORT.
diff --git a/docs/c-api/util.h/mg_start_thread.md b/docs/c-api/util.h/mg_start_thread.md
index 11b66d30aef0635da694de84360774020230b455..4a3c809f9f9a6eb7027ce307bc7c14cfcab374b6 100644
--- a/docs/c-api/util.h/mg_start_thread.md
+++ b/docs/c-api/util.h/mg_start_thread.md
@@ -6,8 +6,8 @@ signature: |
void *mg_start_thread(void *(*thread_func);
---
-Start a new detached thread.
-Arguments and semantic is the same as pthead's `pthread_create()`.
+Starts a new detached thread.
+Arguments and semantics are the same as pthead's `pthread_create()`.
`thread_func` is a thread function, `thread_func_param` is a parameter
that is passed to the thread function.
diff --git a/docs/c-api/util.h/mg_stat.md b/docs/c-api/util.h/mg_stat.md
index 66c3d75f5b83879a61c0baf0db1fd285fbf07096..5bd3b0eb4aabbbdce37597df1304b3d3200a7188 100644
--- a/docs/c-api/util.h/mg_stat.md
+++ b/docs/c-api/util.h/mg_stat.md
@@ -6,7 +6,7 @@ signature: |
int mg_stat(const char *path, cs_stat_t *st);
---
-Perform a 64-bit `stat()` call against given file.
+Performs a 64-bit `stat()` call against a given file.
`path` should be UTF8 encoded.
diff --git a/mongoose.h b/mongoose.h
index 12711a62e3d236477a0069a20e2a68a1e023caa8..bd7088b5259dd1ac93bed8d59a92c2d7a71c0d95 100644
--- a/mongoose.h
+++ b/mongoose.h
@@ -1186,7 +1186,7 @@ struct mg_connection;
/*
* Callback function (event handler) prototype. Must be defined by the user.
- * Mongoose calls the event handler, passing events defined below.
+ * Mongoose calls the event handler, passing the events defined below.
*/
typedef void (*mg_event_handler_t)(struct mg_connection *, int ev, void *);
@@ -1284,53 +1284,53 @@ struct mg_connection {
};
/*
- * Initialize Mongoose manager. Side effect: ignores SIGPIPE signal.
- * `mgr->user_data` field will be initialized with `user_data` parameter.
- * That is an arbitrary pointer, where user code can associate some data
+ * Initialise Mongoose manager. Side effect: ignores SIGPIPE signal.
+ * `mgr->user_data` field will be initialised with a `user_data` parameter.
+ * That is an arbitrary pointer, where the user code can associate some data
* with the particular Mongoose manager. For example, a C++ wrapper class
- * could be written, in which case `user_data` can hold a pointer to the
+ * could be written in which case `user_data` can hold a pointer to the
* class instance.
*/
void mg_mgr_init(struct mg_mgr *mgr, void *user_data);
/*
- * De-initializes Mongoose manager.
+ * De-initialises Mongoose manager.
*
- * Close and deallocate all active connections.
+ * Closes and deallocates all active connections.
*/
void mg_mgr_free(struct mg_mgr *);
/*
- * This function performs the actual IO, and must be called in a loop
- * (an event loop). Returns the current timestamp.
+ * This function performs the actual IO and must be called in a loop
+ * (an event loop). It returns the current timestamp.
* `milli` is the maximum number of milliseconds to sleep.
- * `mg_mgr_poll()` checks all connection for IO readiness. If at least one
- * of the connections is IO-ready, `mg_mgr_poll()` triggers respective
+ * `mg_mgr_poll()` checks all connections for IO readiness. If at least one
+ * of the connections is IO-ready, `mg_mgr_poll()` triggers the respective
* event handlers and returns.
*/
time_t mg_mgr_poll(struct mg_mgr *, int milli);
#ifndef MG_DISABLE_SOCKETPAIR
/*
- * Pass a message of a given length to all connections.
+ * Passes a message of a given length to all connections.
*
* Must be called from a thread that does NOT call `mg_mgr_poll()`.
* Note that `mg_broadcast()` is the only function
* that can be, and must be, called from a different (non-IO) thread.
*
* `func` callback function will be called by the IO thread for each
- * connection. When called, event would be `MG_EV_POLL`, and message will
- * be passed as `ev_data` pointer. Maximum message size is capped
+ * connection. When called, the event will be `MG_EV_POLL`, and a message will
+ * be passed as the `ev_data` pointer. Maximum message size is capped
* by `MG_CTL_MSG_MESSAGE_SIZE` which is set to 8192 bytes.
*/
void mg_broadcast(struct mg_mgr *, mg_event_handler_t func, void *, size_t);
#endif
/*
- * Iterate over all active connections.
+ * Iterates over all active connections.
*
- * Returns next connection from the list
- * of active connections, or `NULL` if there is no more connections. Below
+ * Returns the next connection from the list
+ * of active connections or `NULL` if there are no more connections. Below
* is the iteration idiom:
*
* ```c
@@ -1354,16 +1354,16 @@ struct mg_add_sock_opts {
};
/*
- * Create a connection, associate it with the given socket and event handler,
- * and add it to the manager.
+ * Creates a connection, associates it with the given socket and event handler
+ * and adds it to the manager.
*
* For more options see the `mg_add_sock_opt` variant.
*/
struct mg_connection *mg_add_sock(struct mg_mgr *, sock_t, mg_event_handler_t);
/*
- * Create a connection, associate it with the given socket and event handler,
- * and add to the manager.
+ * Creates a connection, associates it with the given socket and event handler
+ * and adds to the manager.
*
* See the `mg_add_sock_opts` structure for a description of the options.
*/
@@ -1392,28 +1392,29 @@ struct mg_bind_opts {
};
/*
- * Create listening connection.
+ * Creates a listening connection.
*
* See `mg_bind_opt` for full documentation.
*/
struct mg_connection *mg_bind(struct mg_mgr *, const char *,
mg_event_handler_t);
/*
- * Create listening connection.
+ * Creates a listening connection.
*
- * `address` parameter tells which address to bind to. It's format is the same
- * as for the `mg_connect()` call, where `HOST` part is optional. `address`
- * can be just a port number, e.g. `:8000`. To bind to a specific interface,
- * an IP address can be specified, e.g. `1.2.3.4:8000`. By default, a TCP
- * connection is created. To create UDP connection, prepend `udp://` prefix,
- * e.g. `udp://:8000`. To summarize, `address` paramer has following format:
- * `[PROTO://][IP_ADDRESS]:PORT`, where `PROTO` could be `tcp` or `udp`.
+ * The `address` parameter specifies which address to bind to. It's format is
+ * the same as for the `mg_connect()` call, where `HOST` part is optional.
+ * `address` can be just a port number, e.g. `:8000`. To bind to a specific
+ * interface, an IP address can be specified, e.g. `1.2.3.4:8000`. By default,
+ * a TCP connection is created. To create UDP connection, prepend `udp://`
+ * prefix, e.g. `udp://:8000`. To summarize, `address` paramer has following
+ * format: `[PROTO://][IP_ADDRESS]:PORT`, where `PROTO` could be `tcp` or
+ * `udp`.
*
* See the `mg_bind_opts` structure for a description of the optional
* parameters.
*
- * Return a new listening connection, or `NULL` on error.
- * NOTE: Connection remains owned by the manager, do not free().
+ * Returns a new listening connection or `NULL` on error.
+ * NOTE: The connection remains owned by the manager, do not free().
*/
struct mg_connection *mg_bind_opt(struct mg_mgr *mgr, const char *address,
mg_event_handler_t handler,
@@ -1446,7 +1447,7 @@ struct mg_connect_opts {
};
/*
- * Connect to a remote host.
+ * Connects to a remote host.
*
* See `mg_connect_opt()` for full documentation.
*/
@@ -1454,11 +1455,11 @@ struct mg_connection *mg_connect(struct mg_mgr *mgr, const char *address,
mg_event_handler_t handler);
/*
- * Connect to a remote host.
+ * Connects to a remote host.
*
- * `address` format is `[PROTO://]HOST:PORT`. `PROTO` could be `tcp` or `udp`.
- * `HOST` could be an IP address,
- * IPv6 address (if Mongoose is compiled with `-DMG_ENABLE_IPV6`), or a host
+ * The `address` format is `[PROTO://]HOST:PORT`. `PROTO` could be `tcp` or
+ * `udp`. `HOST` could be an IP address,
+ * IPv6 address (if Mongoose is compiled with `-DMG_ENABLE_IPV6`) or a host
* name. If `HOST` is a name, Mongoose will resolve it asynchronously. Examples
* of valid addresses: `google.com:80`, `udp://1.2.3.4:53`, `10.0.0.1:443`,
* `[::1]:80`
@@ -1466,18 +1467,18 @@ struct mg_connection *mg_connect(struct mg_mgr *mgr, const char *address,
* See the `mg_connect_opts` structure for a description of the optional
* parameters.
*
- * Returns a new outbound connection, or `NULL` on error.
+ * Returns a new outbound connection or `NULL` on error.
*
- * NOTE: Connection remains owned by the manager, do not free().
+ * NOTE: The connection remains owned by the manager, do not free().
*
- * NOTE: To enable IPv6 addresses, `-DMG_ENABLE_IPV6` should be specified
+ * NOTE: To enable IPv6 addresses `-DMG_ENABLE_IPV6` should be specified
* in the compilation flags.
*
- * NOTE: New connection will receive `MG_EV_CONNECT` as it's first event
- * which will report connect success status.
- * If asynchronous resolution fail, or `connect()` syscall fail for whatever
- * reason (e.g. with `ECONNREFUSED` or `ENETUNREACH`), then `MG_EV_CONNECT`
- * event report failure. Code example below:
+ * NOTE: The new connection will receive `MG_EV_CONNECT` as its first event
+ * which will report the connect success status.
+ * If the asynchronous resolution fails or the `connect()` syscall fails for
+ * whatever reason (e.g. with `ECONNREFUSED` or `ENETUNREACH`), then
+ * `MG_EV_CONNECT` event will report failure. Code example below:
*
* ```c
* static void ev_handler(struct mg_connection *nc, int ev, void *ev_data) {
@@ -1507,24 +1508,25 @@ struct mg_connection *mg_connect_opt(struct mg_mgr *mgr, const char *address,
#if defined(MG_ENABLE_SSL) && !defined(MG_SOCKET_SIMPLELINK)
/*
- * Note: This function is deprecated, please use SSL options in mg_connect_opt.
+ * Note: This function is deprecated. Please, use SSL options in
+ * mg_connect_opt.
*
- * Enable SSL for a given connection.
- * `cert` is a server certificate file name for a listening connection,
+ * Enables SSL for a given connection.
+ * `cert` is a server certificate file name for a listening connection
* or a client certificate file name for an outgoing connection.
- * Certificate files must be in PEM format. Server certificate file
+ * The certificate files must be in PEM format. The server certificate file
* must contain a certificate, concatenated with a private key, optionally
* concatenated with DH parameters.
- * `ca_cert` is a CA certificate, or NULL if peer verification is not
+ * `ca_cert` is a CA certificate or NULL if peer verification is not
* required.
- * Return: NULL on success, or error message on error.
+ * Return: NULL on success or error message on error.
*/
const char *mg_set_ssl(struct mg_connection *nc, const char *cert,
const char *ca_cert);
#endif
/*
- * Send data to the connection.
+ * Sends data to the connection.
*
* Note that sending functions do not actually push data to the socket.
* They just append data to the output buffer. MG_EV_SEND will be delivered when
@@ -1539,7 +1541,7 @@ __attribute__((format(printf, 2, 3)))
/* don't separate from mg_printf declaration */
/*
- * Send `printf`-style formatted data to the connection.
+ * Sends `printf`-style formatted data to the connection.
*
* See `mg_send` for more details on send semantics.
*/
@@ -1549,9 +1551,9 @@ int mg_printf(struct mg_connection *, const char *fmt, ...);
int mg_vprintf(struct mg_connection *, const char *fmt, va_list ap);
/*
- * Create a socket pair.
+ * Creates a socket pair.
* `sock_type` can be either `SOCK_STREAM` or `SOCK_DGRAM`.
- * Return 0 on failure, 1 on success.
+ * Returns 0 on failure and 1 on success.
*/
int mg_socketpair(sock_t[2], int sock_type);
@@ -1577,47 +1579,47 @@ int mg_resolve(const char *domain_name, char *ip_addr_buf, size_t buf_len);
* Each subnet is
* prepended by either a - or a + sign. A plus sign means allow, where a
* minus sign means deny. If a subnet mask is omitted, such as `-1.2.3.4`,
- * this means to deny only that single IP address.
+ * it means that only that single IP address is denied.
* Subnet masks may vary from 0 to 32, inclusive. The default setting
- * is to allow all accesses. On each request the full list is traversed,
+ * is to allow all access. On each request the full list is traversed,
* and the last match wins. Example:
*
* `-0.0.0.0/0,+192.168/16` - deny all acccesses, only allow 192.168/16 subnet
*
- * To learn more about subnet masks, see the
- * link:https://en.wikipedia.org/wiki/Subnetwork[Wikipedia page on Subnetwork]
+ * To learn more about subnet masks, see this
+ * link:https://en.wikipedia.org/wiki/Subnetwork[Wikipedia page on Subnetwork].
*
- * Return -1 if ACL is malformed, 0 if address is disallowed, 1 if allowed.
+ * Returns -1 if ACL is malformed, 0 if address is disallowed, 1 if allowed.
*/
int mg_check_ip_acl(const char *acl, uint32_t remote_ip);
/*
- * Enable multi-threaded handling for the given listening connection `nc`.
+ * Enables multi-threaded handling for the given listening connection `nc`.
* For each accepted connection, Mongoose will create a separate thread
- * and run event handler in that thread. Thus, if an event hanler is doing
- * a blocking call or some long computation, that will not slow down
+ * and run an event handler in that thread. Thus, if an event handler is doing
+ * a blocking call or some long computation, it will not slow down
* other connections.
*/
void mg_enable_multithreading(struct mg_connection *nc);
#ifdef MG_ENABLE_JAVASCRIPT
/*
- * Enable server-side JavaScript scripting.
- * Requires `-DMG_ENABLE_JAVASCRIPT` compilation flag, and V7 engine sources.
- * v7 instance must not be destroyed during manager's lifetime.
- * Return V7 error.
+ * Enables server-side JavaScript scripting.
+ * Requires a `-DMG_ENABLE_JAVASCRIPT` compilation flag and V7 engine sources.
+ * V7 instance must not be destroyed during manager's lifetime.
+ * Returns a V7 error.
*/
enum v7_err mg_enable_javascript(struct mg_mgr *m, struct v7 *v7,
const char *init_js_file_name);
#endif
/*
- * Schedule MG_EV_TIMER event to be delivered at `timestamp` time.
- * `timestamp` is a UNIX time (a number of seconds since Epoch). It is
+ * Schedules an MG_EV_TIMER event to be delivered at `timestamp` time.
+ * `timestamp` is UNIX time (the number of seconds since Epoch). It is
* `double` instead of `time_t` to allow for sub-second precision.
- * Return the old timer value.
+ * Returns the old timer value.
*
- * Example: set connect timeout to 1.5 seconds:
+ * Example: set the connect timeout to 1.5 seconds:
*
* ```
* c = mg_connect(&mgr, "cesanta.com", ev_handler);
@@ -1810,13 +1812,13 @@ extern "C" {
#endif
/*
- * Fetch substring from input string `s`, `end` into `v`.
+ * Fetches substring from input string `s`, `end` into `v`.
* Skips initial delimiter characters. Records first non-delimiter character
- * as the beginning of substring `v`. Then scans the rest of the string
+ * at the beginning of substring `v`. Then scans the rest of the string
* until a delimiter character or end-of-string is found.
* `delimiters` is a 0-terminated string containing delimiter characters.
* Either one of `delimiters` or `end_string` terminates the search.
- * Return an `s` pointer, advanced forward where parsing stopped.
+ * Returns an `s` pointer, advanced forward where parsing has stopped.
*/
const char *mg_skip(const char *s, const char *end_string,
const char *delimiters, struct mg_str *v);
@@ -1832,13 +1834,14 @@ int mg_ncasecmp(const char *s1, const char *s2, size_t len);
int mg_casecmp(const char *s1, const char *s2);
/*
- * Decode base64-encoded string `s`, `len` into the destination `dst`.
- * Destination has to have enough space to hold decoded buffer.
- * Decoding stops either when all string has been decoded, or invalid
+ * Decodes base64-encoded string `s`, `len` into the destination `dst`.
+ * The destination has to have enough space to hold the decoded buffer.
+ * Decoding stops either when all strings have been decoded or invalid an
* character appeared.
* Destination is '\0'-terminated.
- * Return number of decoded characters. On success, that should be equal to
- * `len`. On error (invalid character) the return value is smaller then `len`.
+ * Returns the number of decoded characters. On success, that should be equal
+ * to `len`. On error (invalid character) the return value is smaller then
+ * `len`.
*/
int mg_base64_decode(const unsigned char *s, int len, char *dst);
@@ -1851,7 +1854,7 @@ void mg_base64_encode(const unsigned char *src, int src_len, char *dst);
#ifndef MG_DISABLE_FILESYSTEM
/*
- * Perform a 64-bit `stat()` call against given file.
+ * Performs a 64-bit `stat()` call against a given file.
*
* `path` should be UTF8 encoded.
*
@@ -1860,7 +1863,7 @@ void mg_base64_encode(const unsigned char *src, int src_len, char *dst);
int mg_stat(const char *path, cs_stat_t *st);
/*
- * Open the given file and return a file stream.
+ * Opens the given file and returns a file stream.
*
* `path` and `mode` should be UTF8 encoded.
*
@@ -1869,7 +1872,7 @@ int mg_stat(const char *path, cs_stat_t *st);
FILE *mg_fopen(const char *path, const char *mode);
/*
- * Open the given file and return a file stream.
+ * Opens the given file and returns a file stream.
*
* `path` should be UTF8 encoded.
*
@@ -1884,8 +1887,8 @@ int mg_open(const char *path, int flag, int mode);
#ifdef MG_ENABLE_THREADS
/*
- * Start a new detached thread.
- * Arguments and semantic is the same as pthead's `pthread_create()`.
+ * Starts a new detached thread.
+ * Arguments and semantics are the same as pthead's `pthread_create()`.
* `thread_func` is a thread function, `thread_func_param` is a parameter
* that is passed to the thread function.
*/
@@ -1898,9 +1901,9 @@ void mg_set_close_on_exec(sock_t);
#define MG_SOCK_STRINGIFY_PORT 2
#define MG_SOCK_STRINGIFY_REMOTE 4
/*
- * Convert connection's local or remote address into string.
+ * Converts a connection's local or remote address into string.
*
- * The `flags` parameter is a bit mask that controls the behavior,
+ * The `flags` parameter is a bit mask that controls the behaviour,
* see `MG_SOCK_STRINGIFY_*` definitions.
*
* - MG_SOCK_STRINGIFY_IP - print IP address
@@ -1917,7 +1920,7 @@ void mg_sock_to_str(sock_t sock, char *buf, size_t len, int flags);
#endif
/*
- * Convert socket's address into string.
+ * Convert the socket's address into string.
*
* `flags` is MG_SOCK_STRINGIFY_IP and/or MG_SOCK_STRINGIFY_PORT.
*/
@@ -1925,28 +1928,28 @@ void mg_sock_addr_to_str(const union socket_address *sa, char *buf, size_t len,
int flags);
/*
- * Generates human-readable hexdump of memory chunk.
+ * Generates a human-readable hexdump of memory chunk.
*
* Takes a memory buffer `buf` of length `len` and creates a hex dump of that
- * buffer in `dst`. Generated output is a-la hexdump(1).
- * Return length of generated string, excluding terminating `\0`. If returned
- * length is bigger than `dst_len`, overflow bytes are discarded.
+ * buffer in `dst`. The generated output is a-la hexdump(1).
+ * Returns the length of generated string, excluding terminating `\0`. If
+ * returned length is bigger than `dst_len`, the overflow bytes are discarded.
*/
int mg_hexdump(const void *buf, int len, char *dst, int dst_len);
/*
- * Generates human-readable hexdump of the data sent or received by connection.
- * `path` is a file name where hexdump should be written. `num_bytes` is
- * a number of bytes sent/received. `ev` is one of the `MG_*` events sent to
- * an event handler. This function is supposed to be called from the
- * event handler.
+ * Generates human-readable hexdump of the data sent or received by the
+ * connection. `path` is a file name where hexdump should be written.
+ * `num_bytes` is a number of bytes sent/received. `ev` is one of the `MG_*`
+ * events sent to an event handler. This function is supposed to be called from
+ * the event handler.
*/
void mg_hexdump_connection(struct mg_connection *nc, const char *path,
const void *buf, int num_bytes, int ev);
/*
- * Print message to buffer. If buffer is large enough to hold the message,
- * return buffer. If buffer is to small, allocate large enough buffer on heap,
- * and return allocated buffer.
+ * Prints message to the buffer. If the buffer is large enough to hold the
+ * message, it returns buffer. If buffer is to small, it allocates a large
+ * enough buffer on heap and returns allocated buffer.
* This is a supposed use case:
*
* char buf[5], *p = buf;
@@ -1961,18 +1964,18 @@ void mg_hexdump_connection(struct mg_connection *nc, const char *path,
int mg_avprintf(char **buf, size_t size, const char *fmt, va_list ap);
/*
- * Return true if target platform is big endian.
+ * Returns true if target platform is big endian.
*/
int mg_is_big_endian(void);
/*
* A helper function for traversing a comma separated list of values.
- * It returns a list pointer shifted to the next value, or NULL if the end
+ * It returns a list pointer shifted to the next value or NULL if the end
* of the list found.
- * Value is stored in val vector. If value has form "x=y", then eq_val
- * vector is initialized to point to the "y" part, and val vector length
+ * The value is stored in a val vector. If the value has a form "x=y", then
+ * eq_val vector is initialised to point to the "y" part, and val vector length
* is adjusted to point only to "x".
- * If list is just a comma separated list of entries, like "aa,bb,cc" then
+ * If the list is just a comma separated list of entries, like "aa,bb,cc" then
* `eq_val` will contain zero-length string.
*
* The purpose of this function is to parse comma separated string without
@@ -1982,9 +1985,11 @@ const char *mg_next_comma_list_entry(const char *list, struct mg_str *val,
struct mg_str *eq_val);
/*
- * Match 0-terminated string (mg_match_prefix) or string with given length
+ * Matches 0-terminated string (mg_match_prefix) or string with given length
* mg_match_prefix_n against a glob pattern.
- * Match is case-insensitive. Return number of bytes matched, or -1 if no match.
+ *
+ * Match is case-insensitive. Returns number of bytes matched, or -1 if no
+ * match.
*/
int mg_match_prefix(const char *pattern, int pattern_len, const char *str);
int mg_match_prefix_n(const struct mg_str pattern, const struct mg_str str);
@@ -2114,40 +2119,41 @@ struct mg_http_multipart_part {
#endif
/*
- * 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
@@ -2195,7 +2201,7 @@ void mg_send_websocket_handshake2(struct mg_connection *nc, const char *path,
*
* `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.
*
@@ -2218,8 +2224,8 @@ struct mg_connection *mg_connect_ws(struct mg_mgr *mgr,
/*
* 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)
*/
struct mg_connection *mg_connect_ws_opt(struct mg_mgr *mgr,
mg_event_handler_t ev_handler,
@@ -2228,9 +2234,9 @@ struct mg_connection *mg_connect_ws_opt(struct mg_mgr *mgr,
const char *extra_headers);
/*
- * 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
@@ -2249,7 +2255,7 @@ void mg_send_websocket_frame(struct mg_connection *nc, int op_and_flags,
const void *data, size_t data_len);
/*
- * Send multiple websocket frames.
+ * Sends multiple websocket frames.
*
* Like `mg_send_websocket_frame()`, but composes a frame from multiple buffers.
*/
@@ -2257,9 +2263,9 @@ void mg_send_websocket_framev(struct mg_connection *nc, int op_and_flags,
const struct mg_str *strings, int num_strings);
/*
- * 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.
*/
void mg_printf_websocket_frame(struct mg_connection *nc, int op_and_flags,
@@ -2267,16 +2273,17 @@ void mg_printf_websocket_frame(struct mg_connection *nc, int op_and_flags,
#endif /* MG_DISABLE_HTTP_WEBSOCKET */
/*
- * 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:
*
* ```
@@ -2287,13 +2294,13 @@ void mg_printf_websocket_frame(struct mg_connection *nc, int op_and_flags,
void mg_send_http_chunk(struct mg_connection *nc, const char *buf, size_t len);
/*
- * Send printf-formatted HTTP chunk.
+ * Sends a printf-formatted HTTP chunk.
* Functionality is similar to `mg_send_http_chunk()`.
*/
void mg_printf_http_chunk(struct mg_connection *nc, const char *fmt, ...);
/*
- * 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:
@@ -2309,23 +2316,23 @@ void mg_send_response_line(struct mg_connection *c, int status_code,
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.
*/
void mg_send_head(struct mg_connection *n, int status_code,
int64_t content_length, const char *extra_headers);
/*
- * Send printf-formatted HTTP chunk, escaping HTML tags.
+ * Sends a printf-formatted HTTP chunk, escaping HTML tags.
*/
void mg_printf_html_escape(struct mg_connection *nc, const char *fmt, ...);
@@ -2352,17 +2359,17 @@ void mg_printf_html_escape(struct mg_connection *nc, const char *fmt, ...);
#define WEBSOCKET_DONT_FIN 0x100
/*
- * 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.
*/
int mg_parse_http(const char *s, int n, struct http_message *hm, int is_req);
/*
- * 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");
@@ -2370,31 +2377,31 @@ int mg_parse_http(const char *s, int n, struct http_message *hm, int is_req);
struct mg_str *mg_get_http_header(struct http_message *hm, const char *name);
/*
- * 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.
*/
int mg_http_parse_header(struct mg_str *hdr, const char *var_name, char *buf,
size_t buf_size);
/*
- * 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:
@@ -2429,46 +2436,46 @@ size_t mg_parse_multipart(const char *buf, size_t buf_len, char *var_name,
size_t *chunk_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.
*/
int mg_get_http_var(const struct mg_str *buf, const char *name, char *dst,
size_t dst_len);
/*
- * 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`.
*/
int mg_url_decode(const char *src, int src_len, char *dst, int dst_len,
int is_form_url_encoded);
-/* Create Digest authentication header for client request. */
+/* Creates digest authentication header for a client request. */
int mg_http_create_digest_auth_header(char *buf, size_t buf_len,
const char *method, const char *uri,
const char *auth_domain, const char *user,
const char *passwd);
/*
- * 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:
*
@@ -2489,10 +2496,11 @@ struct mg_connection *mg_connect_http(struct mg_mgr *mgr,
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)
*/
struct mg_connection *mg_connect_http_opt(struct mg_mgr *mgr,
mg_event_handler_t ev_handler,
@@ -2657,7 +2665,7 @@ struct mg_serve_http_opts {
};
/*
- * Serve given HTTP request according to the `options`.
+ * Serves given HTTP request according to the `options`.
*
* Example code snippet:
*
@@ -2680,8 +2688,8 @@ void mg_serve_http(struct mg_connection *nc, struct http_message *hm,
struct mg_serve_http_opts opts);
/*
- * 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:
@@ -2721,9 +2729,10 @@ typedef struct mg_str (*mg_fu_fname_fn)(struct mg_connection *nc,
* 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:
@@ -2751,7 +2760,7 @@ void mg_file_upload_handler(struct mg_connection *nc, int ev, void *ev_data,
#endif /* MG_ENABLE_HTTP_STREAMING_MULTIPART */
/*
- * Authenticate HTTP request against opened passwords file.
+ * Authenticates a HTTP request against an opened password file.
* Returns 1 if authenticated, 0 otherwise.
*/
int mg_http_check_digest_auth(struct http_message *hm, const char *auth_domain,
@@ -2872,7 +2881,7 @@ extern "C" {
#endif /* __cplusplus */
/*
- * Attach built-in MQTT event handler to the given connection.
+ * Attaches a built-in MQTT event handler to the given connection.
*
* The user-defined event handler will receive following extra events:
*
@@ -2886,66 +2895,66 @@ extern "C" {
*/
void mg_set_protocol_mqtt(struct mg_connection *nc);
-/* Send MQTT handshake. */
+/* Sends an MQTT handshake. */
void mg_send_mqtt_handshake(struct mg_connection *nc, const char *client_id);
-/* Send MQTT handshake with optional parameters. */
+/* Sends an MQTT handshake with optional parameters. */
void mg_send_mqtt_handshake_opt(struct mg_connection *nc, const char *client_id,
struct mg_send_mqtt_handshake_opts);
-/* Publish a message to a given topic. */
+/* Publishes a message to a given topic. */
void mg_mqtt_publish(struct mg_connection *nc, const char *topic,
uint16_t message_id, int flags, const void *data,
size_t len);
-/* Subscribe to a bunch of topics. */
+/* Subscribes to a bunch of topics. */
void mg_mqtt_subscribe(struct mg_connection *nc,
const struct mg_mqtt_topic_expression *topics,
size_t topics_len, uint16_t message_id);
-/* Unsubscribe from a bunch of topics. */
+/* Unsubscribes from a bunch of topics. */
void mg_mqtt_unsubscribe(struct mg_connection *nc, char **topics,
size_t topics_len, uint16_t message_id);
-/* Send a DISCONNECT command. */
+/* Sends a DISCONNECT command. */
void mg_mqtt_disconnect(struct mg_connection *nc);
-/* Send a CONNACK command with a given `return_code`. */
+/* Sends a CONNACK command with a given `return_code`. */
void mg_mqtt_connack(struct mg_connection *nc, uint8_t return_code);
-/* Send a PUBACK command with a given `message_id`. */
+/* Sends a PUBACK command with a given `message_id`. */
void mg_mqtt_puback(struct mg_connection *nc, uint16_t message_id);
-/* Send a PUBREC command with a given `message_id`. */
+/* Sends a PUBREC command with a given `message_id`. */
void mg_mqtt_pubrec(struct mg_connection *nc, uint16_t message_id);
-/* Send a PUBREL command with a given `message_id`. */
+/* Sends a PUBREL command with a given `message_id`. */
void mg_mqtt_pubrel(struct mg_connection *nc, uint16_t message_id);
-/* Send a PUBCOMP command with a given `message_id`. */
+/* Sends a PUBCOMP command with a given `message_id`. */
void mg_mqtt_pubcomp(struct mg_connection *nc, uint16_t message_id);
/*
- * Send a SUBACK command with a given `message_id`
+ * Sends a SUBACK command with a given `message_id`
* and a sequence of granted QoSs.
*/
void mg_mqtt_suback(struct mg_connection *nc, uint8_t *qoss, size_t qoss_len,
uint16_t message_id);
-/* Send a UNSUBACK command with a given `message_id`. */
+/* Sends a UNSUBACK command with a given `message_id`. */
void mg_mqtt_unsuback(struct mg_connection *nc, uint16_t message_id);
-/* Send a PINGREQ command. */
+/* Sends a PINGREQ command. */
void mg_mqtt_ping(struct mg_connection *nc);
-/* Send a PINGRESP command. */
+/* Sends a PINGRESP command. */
void mg_mqtt_pong(struct mg_connection *nc);
/*
- * Extract the next topic expression from a SUBSCRIBE command payload.
+ * Extracts the next topic expression from a SUBSCRIBE command payload.
*
- * Topic expression name will point to a string in the payload buffer.
- * Return the pos of the next topic expression or -1 when the list
+ * The topic expression name will point to a string in the payload buffer.
+ * Returns the pos of the next topic expression or -1 when the list
* of topics is exhausted.
*/
int mg_mqtt_next_subscribe_topic(struct mg_mqtt_message *msg,
@@ -3007,14 +3016,14 @@ struct mg_mqtt_broker {
void *user_data; /* User data */
};
-/* Initialize a MQTT broker. */
+/* Initialises a MQTT broker. */
void mg_mqtt_broker_init(struct mg_mqtt_broker *brk, void *user_data);
/*
- * Process a MQTT broker message.
+ * Processes a MQTT broker message.
*
- * Listening connection expects a pointer to an initialized `mg_mqtt_broker`
- * structure in the `user_data` field.
+ * The listening connection expects a pointer to an initialised
+ * `mg_mqtt_broker` structure in the `user_data` field.
*
* Basic usage:
*
@@ -3038,7 +3047,7 @@ void mg_mqtt_broker_init(struct mg_mqtt_broker *brk, void *user_data);
void mg_mqtt_broker(struct mg_connection *brk, int ev, void *data);
/*
- * Iterate over all mqtt sessions connections. Example:
+ * Iterates over all MQTT session connections. Example:
*
* ```c
* struct mg_mqtt_session *s;
@@ -3114,7 +3123,7 @@ struct mg_dns_resource_record *mg_dns_next_record(
struct mg_dns_message *msg, int query, struct mg_dns_resource_record *prev);
/*
- * Parse the record data from a DNS resource record.
+ * Parses the record data from a DNS resource record.
*
* - A: struct in_addr *ina
* - AAAA: struct in6_addr *ina
@@ -3129,35 +3138,35 @@ int mg_dns_parse_record_data(struct mg_dns_message *msg,
size_t data_len);
/*
- * Send a DNS query to the remote end.
+ * Sends a DNS query to the remote end.
*/
void mg_send_dns_query(struct mg_connection *nc, const char *name,
int query_type);
/*
- * Insert a DNS header to an IO buffer.
+ * Inserts a DNS header to an IO buffer.
*
- * Return number of bytes inserted.
+ * Returns the number of bytes inserted.
*/
int mg_dns_insert_header(struct mbuf *io, size_t pos,
struct mg_dns_message *msg);
/*
- * Append already encoded questions from an existing message.
+ * Appends already encoded questions from an existing message.
*
* This is useful when generating a DNS reply message which includes
* all question records.
*
- * Return number of appened bytes.
+ * Returns the number of appended bytes.
*/
int mg_dns_copy_questions(struct mbuf *io, struct mg_dns_message *msg);
/*
- * Encode and append a DNS resource record to an IO buffer.
+ * Encodes and appends a DNS resource record to an IO buffer.
*
* The record metadata is taken from the `rr` parameter, while the name and data
* are taken from the parameters, encoded in the appropriate format depending on
- * record type, and stored in the IO buffer. The encoded values might contain
+ * record type and stored in the IO buffer. The encoded values might contain
* offsets within the IO buffer. It's thus important that the IO buffer doesn't
* get trimmed while a sequence of records are encoded while preparing a DNS
*reply.
@@ -3166,7 +3175,7 @@ int mg_dns_copy_questions(struct mbuf *io, struct mg_dns_message *msg);
*struct
* because they might be invalidated as soon as the IO buffer grows again.
*
- * Return the number of bytes appened or -1 in case of error.
+ * Returns the number of bytes appened or -1 in case of error.
*/
int mg_dns_encode_record(struct mbuf *io, struct mg_dns_resource_record *rr,
const char *name, size_t nlen, const void *rdata,
@@ -3176,27 +3185,27 @@ int mg_dns_encode_record(struct mbuf *io, struct mg_dns_resource_record *rr,
int mg_parse_dns(const char *buf, int len, struct mg_dns_message *msg);
/*
- * Uncompress a DNS compressed name.
+ * Uncompresses a DNS compressed name.
*
- * The containing dns message is required because the compressed encoding
+ * The containing DNS message is required because of the compressed encoding
* and reference suffixes present elsewhere in the packet.
*
- * If name is less than `dst_len` characters long, the remainder
- * of `dst` is terminated with `\0' characters. Otherwise, `dst` is not
- *terminated.
+ * If the name is less than `dst_len` characters long, the remainder
+ * of `dst` is terminated with `\0` characters. Otherwise, `dst` is not
+ * terminated.
*
* If `dst_len` is 0 `dst` can be NULL.
- * Return the uncompressed name length.
+ * Returns the uncompressed name length.
*/
size_t mg_dns_uncompress_name(struct mg_dns_message *msg, struct mg_str *name,
char *dst, int dst_len);
/*
- * Attach built-in DNS event handler to the given listening connection.
+ * Attaches a built-in DNS event handler to the given listening connection.
*
- * DNS event handler parses incoming UDP packets, treating them as DNS
- * requests. If incoming packet gets successfully parsed by the DNS event
- * handler, a user event handler will receive `MG_DNS_REQUEST` event, with
+ * The DNS event handler parses the incoming UDP packets, treating them as DNS
+ * requests. If an incoming packet gets successfully parsed by the DNS event
+ * handler, a user event handler will receive an `MG_DNS_REQUEST` event, with
* `ev_data` pointing to the parsed `struct mg_dns_message`.
*
* See
@@ -3239,18 +3248,18 @@ struct mg_dns_reply {
};
/*
- * Create a DNS reply.
+ * Creates a DNS reply.
*
* The reply will be based on an existing query message `msg`.
* The query body will be appended to the output buffer.
- * "reply + recursion allowed" will be added to the message flags and
+ * "reply + recursion allowed" will be added to the message flags and the
* message's num_answers will be set to 0.
*
* Answer records can be appended with `mg_dns_send_reply` or by lower
* level function defined in the DNS API.
*
- * In order to send the reply use `mg_dns_send_reply`.
- * It's possible to use a connection's send buffer as reply buffers,
+ * In order to send a reply use `mg_dns_send_reply`.
+ * It's possible to use a connection's send buffer as reply buffer,
* and it will work for both UDP and TCP connections.
*
* Example:
@@ -3270,10 +3279,10 @@ struct mg_dns_reply mg_dns_create_reply(struct mbuf *io,
struct mg_dns_message *msg);
/*
- * Append a DNS reply record to the IO buffer and to the DNS message.
+ * Appends a DNS reply record to the IO buffer and to the DNS message.
*
- * The message num_answers field will be incremented. It's caller's duty
- * to ensure num_answers is propertly initialized.
+ * The message's num_answers field will be incremented. It's the caller's duty
+ * to ensure num_answers is properly initialised.
*
* Returns -1 on error.
*/
@@ -3283,12 +3292,12 @@ int mg_dns_reply_record(struct mg_dns_reply *reply,
size_t rdata_len);
/*
- * Send a DNS reply through a connection.
+ * Sends a DNS reply through a connection.
*
* The DNS data is stored in an IO buffer pointed by reply structure in `r`.
* This function mutates the content of that buffer in order to ensure that
- * the DNS header reflects size and flags of the mssage, that might have been
- * updated either with `mg_dns_reply_record` or by direct manipulation of
+ * the DNS header reflects the size and flags of the message, that might have
+ * been updated either with `mg_dns_reply_record` or by direct manipulation of
* `r->message`.
*
* Once sent, the IO buffer will be trimmed unless the reply IO buffer
@@ -3474,11 +3483,11 @@ struct mg_coap_message {
extern "C" {
#endif /* __cplusplus */
-/* Set CoAP protocol handler - trigger CoAP specific events */
+/* Sets CoAP protocol handler - triggers CoAP specific events. */
int mg_set_protocol_coap(struct mg_connection *nc);
/*
- * Add new option to mg_coap_message structure.
+ * Adds a new option to mg_coap_message structure.
* Returns pointer to the newly created option.
*/
struct mg_coap_option *mg_coap_add_option(struct mg_coap_message *cm,
@@ -3486,15 +3495,15 @@ struct mg_coap_option *mg_coap_add_option(struct mg_coap_message *cm,
size_t len);
/*
- * Free the memory allocated for options,
- * if cm paramater doesn't contain any option does nothing.
+ * Frees the memory allocated for options.
+ * If the cm paramater doesn't contain any option it does nothing.
*/
void mg_coap_free_options(struct mg_coap_message *cm);
/*
- * Compose CoAP message from `mg_coap_message`
- * and send it into `nc` connection.
- * Return 0 on success. On error, it is a bitmask:
+ * Composes a CoAP message from `mg_coap_message`
+ * and sends it into `nc` connection.
+ * Returns 0 on success. On error, it is a bitmask:
*
* - `#define MG_COAP_ERROR 0x10000`
* - `#define MG_COAP_FORMAT_ERROR (MG_COAP_ERROR | 0x20000)`
@@ -3506,20 +3515,20 @@ uint32_t mg_coap_send_message(struct mg_connection *nc,
struct mg_coap_message *cm);
/*
- * Compose CoAP acknowledgement from `mg_coap_message`
- * and send it into `nc` connection.
+ * Composes CoAP acknowledgement from `mg_coap_message`
+ * and sends it into `nc` connection.
* Return value: see `mg_coap_send_message()`
*/
uint32_t mg_coap_send_ack(struct mg_connection *nc, uint16_t msg_id);
/*
- * Parse COAP message and fills mg_coap_message and returns cm->flags.
+ * Parses CoAP message and fills mg_coap_message and returns cm->flags.
* This is a helper function.
*
- * NOTE: usually CoAP work over UDP, so lack of data means format error,
- * but in theory it is possible to use CoAP over TCP (according to RFC)
+ * NOTE: usually CoAP works over UDP, so lack of data means format error.
+ * But, in theory, it is possible to use CoAP over TCP (according to RFC)
*
- * The caller have to check results and treat COAP_NOT_ENOUGH_DATA according to
+ * The caller has to check results and treat COAP_NOT_ENOUGH_DATA according to
* underlying protocol:
*
* - in case of UDP COAP_NOT_ENOUGH_DATA means COAP_FORMAT_ERROR,