Enhanced documentation

docs/api/client_cert.md

@@ -19,3 +19,4 @@ structure to store information of an optional client supplied certificate.
 ### See Also
 
 * [`struct mg_request_info;`](mg_request_info.md)
+* [`mg_get_request_info();`](mg_get_request_info.md)

docs/api/mg_callbacks.md

@@ -60,3 +60,4 @@ should be handled.
 ### See Also
 
 * [`mg_start();`](mg_start.md)
+* [`mg_stop();`](mg_stop.md)

docs/api/mg_client_options.md

@@ -6,13 +6,17 @@
 
 | Field | Type | Description |
 | :--- | :--- | :--- |
-|**`host`**|`const char *`||
-|**`port`**|`int`||
-|**`client_cert`**|`const char *`||
-|**`server_cert`**|`const char *`||
+|**`host`**|`const char *`|The hostname or IP address to connect to|
+|**`port`**|`int`|The port on the server|
+|**`client_cert`**|`const char *`|Pointer to client certificate|
+|**`server_cert`**|`const char *`|Pointer to a server certificate|
 
 ### Description
 
+The the `mgclient_options` structure contains host and security information to connect
+as a client to another host. A parameter of this type is used in the call to the
+function [`mg_connect_client_secure();`](mg_connect_client_secure.md).
+
 ### See Also
 
 * [`mg_connect_client_secure();`](mg_connect_client_secure.md)

docs/api/mg_close_connection.md

@@ -14,6 +14,10 @@
 
 ### Description
 
+The function `mg_close_connection()` is used to close a connection which was opened with the
+[`mg_download()`](mg_download.md) function. Use of this function to close a connection which
+was opened in another way is undocumented and may give unexpected results.
+
 ### See Also
 
 * [`mg_download();`](mg_download.md)

docs/api/mg_connect_client.md

@@ -6,11 +6,11 @@
 
 | Parameter | Type | Description |
 | :--- | :--- | :--- |
-|**`host`**|`const char *`||
-|**`port`**|`int`||
-|**`use_ssl`**|`int`||
-|**`error_buffer`**|`char *`||
-|**`error_buffer_size`**|`size_t`||
+|**`host`**|`const char *`|hostname or IP address of the server|
+|**`port`**|`int`|The port to connect to on the server|
+|**`use_ssl`**|`int`|Connects using SSL of this value is not zero|
+|**`error_buffer`**|`char *`|Buffer to store an error message|
+|**`error_buffer_size`**|`size_t`|Maximum size of the error buffer including the NUL terminator|
 
 ### Return Value
 
@@ -20,6 +20,10 @@
 
 ### Description
 
+The function `mg_connect_client()` connects to a TCP server as a client. This server
+can be a HTTP server but this is not necessary. The function returns a poinyer to
+a connection structure when the connection is established, and NULL otherwise.
+
 ### See Also
 
 * [`mg_connect_client_secure();`](mg_connect_client_secure.md)

docs/api/mg_connect_client_secure.md

@@ -6,9 +6,9 @@
 
 | Parameter | Type | Description |
 | :--- | :--- | :--- |
-|**`client_options`**|`const struct mg_client_options *`||
-|**`error_buffer`**|`char *`||
-|**`error_buffer_size`**|`size_t`||
+|**`client_options`**|`const struct mg_client_options *`|Settings about the server connection|
+|**`error_buffer`**|`char *`|Buffer to store an error message|
+|**`error_buffer_size`**|`size_t`|Size of the error message buffer including the NUL terminator|
 
 ### Return Value
 
@@ -18,6 +18,11 @@
 
 ### Description
 
+The function `mg_connect_client_secure()` creates a secure connection with a server. The
+information about the connection and server is passed in a structure and an error message
+may be returned in a local buffer. The function returns a pointer to an `struct mg_connection`
+structure when successful and NULL otherwise.
+
 ### See Also
 
 * [`struct mg_client_options;`](mg_client_options.md)

docs/api/mg_connect_websocket_client.md

@@ -6,25 +6,29 @@
 
 | Parameter | Type | Description |
 | :--- | :--- | :--- |
-|**`host`**|`const char *`||
-|**`port`**|`int`||
-|**`use_ssl`**|`int`||
-|**`error_buffer`**|`char *`||
-|**`error_buffer_size`**|`size_t`||
-|**`path`**|`const char *`||
-|**`origin`**|`const char *`||
-|**`data_func`**|`mg_websocket_data_handler`||
-|**`close_func`**|`mg_websocket_close_handler`||
-|**`user_data`**|`void *`||
+|**`host`**|`const char *`|The hostname or IP address of the server|
+|**`port`**|`int`|The port on the server|
+|**`use_ssl`**|`int`|Use SSL if this parameter is not equal to zero|
+|**`error_buffer`**|`char *`|Buffer to store an error message|
+|**`error_buffer_size`**|`size_t`|Size of the error message buffer including the NUL terminator|
+|**`path`**|`const char *`|The server path to connect to, for example `/app` if you want to connect to `localhost/app`|
+|**`origin`**|`const char *`|The value of the `Origin` HTTP header|
+|**`data_func`**|`mg_websocket_data_handler`|Callback which is used to process data coming back from the server|
+|**`close_func`**|`mg_websocket_close_handler`|Callback which is called when the connection is to be closed|
+|**`user_data`**|`void *`|User supplied argument|
 
 ### Return Value
 
 | Type | Description |
 | :--- | :--- |
-|`struct mg_connection *`||
+|`struct mg_connection *`|A pointer to the connection structure, or NULL if connecting failed|
 
 ### Description
 
+The function `mg_connect_websocket_client()` connects to a websocket on a server as a client.
+Data and close events are processed with callback functions which must be provided in the
+call.
+
 ### See Also
 
 * [`mg_connect_client();`](mg_connect_client.md)

docs/api/mg_cry.md

@@ -6,9 +6,9 @@
 
 | Parameter | Type | Description |
 | :--- | :--- | :--- |
-|**`conn`**|`const struct mg_connection *`||
-|**`fmt`**|`const char *`||
-|**`...`**|*various*||
+|**`conn`**|`const struct mg_connection *`|The connection on which a problem occured|
+|**`fmt`**|`const char *`|Format string without a line return|
+|**`...`**|*various*|Parameters depending on the format string|
 
 ### Return Value
 
@@ -16,4 +16,12 @@
 
 ### Description
 
+The function `mg_cry()` is called when something happens on a connection. The function
+takes a format string similar to the `printf()` series of functions with parameters and
+creates a text string which can then be used for logging. The `mg_cry()` function
+prints the output to the opened error log stream. Log messages can be processed with the
+`log_message()` callback function specified in the `struct mg_callbacks` structure.
+
 ### See Also
+
+* [`struct mg_callbacks;`](mg_callbacks.md)

docs/api/mg_download.md

@@ -6,22 +6,35 @@
 
 | Parameter | Type | Description |
 | :--- | :--- | :--- |
-|**`host`**|`const char *`||
-|**`port`**|`int`||
-|**`use_ssl`**|`int`||
-|**`error_buffer`**|`char *`||
-|**`error_buffer_size`**|`size_t`||
-|**`fmt`**|`const char *`||
-|**`...`**|*various*||
+|**`host`**|`const char *`|The hostname or IP address of the server|
+|**`port`**|`int`|The port number on the server|
+|**`use_ssl`**|`int`|Use SSL if this value is not equal zero|
+|**`error_buffer`**|`char *`|Buffer to store an error message|
+|**`error_buffer_size`**|`size_t`|Size of the error message buffer including the terminating NUL|
+|**`fmt`**|`const char *`|Format string specifying the remote command to execute|
+|**`...`**|*various*|Parameters used in the format string|
 
 ### Return Value
 
 | Type | Description |
 | :--- | :--- |
-|`struct mg_connection *`||
+|`struct mg_connection *`|A pointer to the connection structure if successful and NULL otherwise|
 
 ### Description
 
+The `mg_download()` function is used to download data from a remote webserver. The server
+address can either be specified as a hostname or IP address and SSL can be used if
+needed. If the function succeeds, a pointer is returned to a connection structure.
+The connection must be closed with a call to the
+[`mg_close_connection()`](mg_close_connection.md) function.
+
+The format string is a format string from the `printf()` series of functions to specify
+the remote command. An example to get the main index page from Google is the following
+call:
+
+`conn = mg_download( "google.com", 80, 0, ebuf, sizeof(ebuf),
+                     "%s", "GET / HTTP/1.0\r\nHost: google.com\r\n\r\n" );`
+
 ### See Also
 
 * [`mg_close_connection();`](mg_close_connection.md)