Added several function descriptions

docs/api/mg_get_cookie.md

@@ -6,8 +6,8 @@
 
 | Parameter | Type | Description |
 | :--- | :--- | :--- |
-|**`cookie`**|`const char *`||
-|**`var_name`**|`const char *`||
+|**`cookie`**|`const char *`|The cookie name|
+|**`var_name`**|`const char *`|The variable name|
 |**`buf`**|`char *`|The buffer where to store the contents of the cookie|
 |**`buf_len`**|`size_t`|The length of the cookie buffer, including the terminating NUL|
 
@@ -19,6 +19,10 @@
 
 ### Description
 
+The function `mg_get_cookie() tries to fetch the value of a certain cookie variable. The contents will either be stored in an application provided buffer, or an error code will be returned. The destination buffer is guaranteed to be NUL terminated if the pointer of the buffer is not a NULL pointer and the size of the buffer is at least one byte.
+
+If the function succeeds, the return value of the function is the length in bytes of the cookie. The value **`-1`** is returned if the requested cookie could not be found and -2 if the destination buffer is represented by a NULL pointer, is zero length or too short to store the whole cookie.
+
 ### See Also
 
 * [`mg_get_var();`](mg_get_var.md)

docs/api/mg_get_ports.md

@@ -7,20 +7,23 @@
 | Parameter | Type | Description |
 | :--- | :--- | :--- |
 |**`ctx`**|`const struct mg_context *`||
-|**`size`**|`size_t`||
-|**`ports`**|`int *`||
-|**`ssl`**|`int *`||
+|**`size`**|`size_t`|The number of ports which can be stored in the buffer|
+|**`ports`**|`int *`|Buffer for storage of the port numbers|
+|**`ssl`**|`int *`|Buffer used to store if SSL is used for the ports|
 
 ### Return Value
 
 | Type | Description |
 | :--- | :--- |
-|`size_t`||
+|`size_t`|The number of ports stored in the buffer|
 
 ### Description
 
-This function is deprecated. Use [`mg_get_server_ports()`](mg_get_server_ports.md)
-instead.
+This function is deprecated. Use [`mg_get_server_ports()`](mg_get_server_ports.md) instead.
+
+The function `mg_get_ports()` returns a list of ports the Civetweb server is listening on. The port numbers are stored in a buffer of integers which is supplied by the calling party. The function also stores information if SSL is used on the ports. This information is stored in a second buffer which should be capable of storing the same amount of items as the ports buffer.
+
+The function returns the number of ports actually stored in the buffer.
 
 ### See Also
 

docs/api/mg_get_request_info.md

@@ -6,16 +6,18 @@
 
 | Parameter | Type | Description |
 | :--- | :--- | :--- |
-|**`conn`**|`const struct mg_connection *`||
+|**`conn`**|`const struct mg_connection *`|The connection for which the request info is needed|
 
 ### Return Value
 
 | Type | Description |
 | :--- | :--- |
-|`const struct mg_request_info *`||
+|`const struct mg_request_info *`|Pointer to the requested info, or NULL if an error occured|
 
 ### Description
 
+The function `mg_get_request_info()` returns information about the request on a given connection. This information is returned as a pointer to a [`mg_request_info`](mg_request_info.md) structure. If an error occurs, a NULL pointer is returned instead.
+
 ### See Also
 
 * [`struct mg_request_info;`](mg_request_info.md)

docs/api/mg_get_response.md

@@ -6,17 +6,24 @@
 
 | Parameter | Type | Description |
 | :--- | :--- | :--- |
-|**`conn`**|`struct mg_connection *`||
-|**`ebuf`**|`char *`||
-|**`ebuf_len`**|`size_t`||
-|**`timeout`**|`int`||
+|**`conn`**|`struct mg_connection *`|The connection to listen on|
+|**`ebuf`**|`char *`|Buffer to store an error message|
+|**`ebuf_len`**|`size_t`|Size of the error message buffer including the terminating NUL|
+|**`timeout`**|`int`|Time to wait for a response in milliseconds|
 
 ### Return Value
 
 | Type | Description |
 | :--- | :--- |
-|`int`||
+|`int`|Success value of the wait|
 
 ### Description
 
+The function `mg_get_reponse()` wait for a response from a remote server. A return value equal or greater than zero is an indication for success, a negative value us used to signal an error condition. A timeout can be specified which lets the function return after a specified number of milliseconds, even if no data is received from the remote party. If the timeout value is negative, the function will not return until data has been read or an unrecoverable error occurs.
+
+Error messages are stored in a caller supplied error message buffer.
+
 ### See Also
+
+* [`mg_connect_client();`](mg_connect_client.md)
+* [`mg_connect_client_secure();`](mg_connect_client_secure.md)

docs/api/mg_get_response_code_text.md

@@ -17,7 +17,9 @@
 
 ### Description
 
-The function `mg_get_response_code_text()` returns a pointer to a human readable text
-describing the HTTP response code which was provided as a parameter.
+The function `mg_get_response_code_text()` returns a pointer to a human readable text describing the HTTP response code which was provided as a parameter.
 
 ### See Also
+
+* [`mg_get_builtin_mime_type();`](mg_get_builtin_mime_type.md)
+* [`mg_version();`](mg_version.md)

docs/api/mg_get_server_ports.md

@@ -6,18 +6,22 @@
 
 | Parameter | Type | Description |
 | :--- | :--- | :--- |
-|**`ctx`**|`const struct mg_context *`||
-|**`size`**|`int`||
-|**`ports`**|`struct mg_server_ports *`||
+|**`ctx`**|`const struct mg_context *`|The context for which the server ports are requested|
+|**`size`**|`int`|The size of the buffer to store the port information|
+|**`ports`**|`struct mg_server_ports *`|Buffer to store the port information|
 
 ### Return Value
 
 | Type | Description |
 | :--- | :--- |
-|`int`||
+|`int`|The actual number of ports returned, or an error condition|
 
 ### Description
 
+The `mg_get_server_ports()` returns a list with server ports on which the Civetweb server is listening. The ports are returned for a given context and stored with additional information like the SSL and redirection state in a list of structures. The list of structures must be allocated by the calling routine. The size of the structure is also passed to `mg_get_server_ports()`.
+
+The function returns the number of items in the list, or a negative value if an error occured.
+
 ### See Also
 
 * [~~`mg_get_ports();`~~](mg_get_ports.md)

docs/api/mg_get_user_connection_data.md

@@ -6,16 +6,18 @@
 
 | Parameter | Type | Description |
 | :--- | :--- | :--- |
-|**`conn`**|`const struct mg_connection *`||
+|**`conn`**|`const struct mg_connection *`|The connection for which to return the user data|
 
 ### Return Value
 
 | Type | Description | 
 | :--- | :--- |
-|`void *`||
+|`void *`|A pointer to the user data, or NULL if no user data was registered with the connection|
 
 ### Description
 
+The function `mg_get_user_connection_data()` returns the user data associated with a connection. This user data is represented with a pointer which has been prevously registered with a call to [`mg_set_user_connection_data();`](mg_set_user_connection_data.md). With this function it is possible to pass state information between callback functions refering to a specific connection.
+
 ### See Also
 
 * [`mg_set_user_connection_data();`](mg_set_user_connection_data.md)

docs/api/mg_get_user_data.md

@@ -6,7 +6,7 @@
 
 | Parameter | Type | Description |
 | :--- | :--- | :--- |
-|**`ctx`**|`const struct mg_context *`||
+|**`ctx`**|`const struct mg_context *`|The context for which the user data is requested|
 
 ### Return Value
 
@@ -16,4 +16,8 @@
 
 ### Description
 
+The function `mg_get_user_data()` returns the user data associated with a Civetweb context. This is a pointer value which has previously been used in the call to [`mg_start()`](mg_start.md) to initialize the server context.
+
 ### See Also
+
+* [`mg_start();`](mg_start.md)

docs/api/mg_get_valid_option_names.md

@@ -10,12 +10,15 @@
 
 | Type | Description |
 | :--- | :--- |
-|`const char **`||
+|`const char **`|An array with strings where the even elements represent the option names, and the odd element the option values The array is NULL terminated.|
 
 ### Description
 
-This function is depricated. Use [`mg_get_valid_options()`](mg_get_valid_options.md) instead.
+The function `mg_get_valid_option_names()` is depricated. Use [`mg_get_valid_options()`](mg_get_valid_options.md) instead.
+
+This function returns an array with option/value pairs describing the valid configuration options for Civetweb. En element value of NULL signals the end of the list.
 
 ### See Also
 
+* [`struct mg_option;`](mg_option.md)
 * [`mg_get_valid_options();`](mg_get_valid_options.md)

docs/api/mg_get_valid_options.md

@@ -10,10 +10,13 @@
 
 | Type | Description | 
 | :--- | :--- |
-|`const struct mg_option *`||
+|`const struct mg_option *`|An array with all valid configuration options|
 
 ### Description
 
+The function `mg_get_valid_options()` returns an array with all valid configuration options of Civetweb. Each element in the array is a structure with three fields which represent the name of the option, the value of the option and the type of the value. The array is terminated with an element for which the name is `NULL`. See for more details about this structure the documentation of [`struct mg_option`](mg_option.md).
+
 ### See Also
 
 * [`struct mg_option;`](mg_option.md)
+* [`mg_start();`](mg_start.md)

docs/api/mg_get_var.md

@@ -6,20 +6,24 @@
 
 | Parameter | Type | Description |
 | :--- | :--- | :--- |
-|**`data`**|`const char *`||
-|**`data_len`**|`size_t`||
-|**`var_name`**|`const char *`||
-|**`dst`**|`char *`||
-|**`dst_len`**|`size_t`||
+|**`data`**|`const char *`|Encoded buffer from either POST data or the URI of a GET call|
+|**`data_len`**|`size_t`|Size of the encode buffer including the terminating NULL|
+|**`var_name`**|`const char *`|Name of the variable to search for|
+|**`dst`**|`char *`|Output buffer to store the content of the variable|
+|**`dst_len`**|`size_t`|Length of the output buffer|
 
 ### Return Value
 
 | Type | Description |
 | :--- | :--- |
-|`int`||
+|`int`|The length of the variable or an error code|
 
 ### Description
 
+The function `mg_get_var()` returns the value of a variable which is passed to the server with either a POST method, or as a parameter in the URI of a GET call. The data pointer passed to the function points to a form-URI encoded buffer. This can either be POST data or the `request_info.query_string`. The name of the searched variable and a buffer to store the results are also parameters to the function.
+
+The function either returns the length of the variable when successful, **`-1`** if the variable could not be found and **`-2`** if the destination buffer is NULL, has size zero or is too small to store the resulting variable value.
+
 ### See Also
 
 * [`mg_get_cookie();`](mg_get_cookie.md)

docs/api/mg_get_var2.md

@@ -6,21 +6,25 @@
 
 | Parameter | Type | Description |
 | :--- | :--- | :--- |
-|**`data`**|`const char *`||
-|**`data_len`**|`size_t`||
-|**`var_name`**|`const char *`||
-|**`dst`**|`char *`||
-|**`dst_len`**|`size_t`||
-|**`occurrence`**|`size_t`||
+|**`data`**|`const char *`|Encoded data buffer from either POST data or a GET URI|
+|**`data_len`**|`size_t`|The size of the encoded data buffer|
+|**`var_name`**|`const char *`|The name of the variable to search for|
+|**`dst`**|`char *`|Destination buffer to store the variable content|
+|**`dst_len`**|`size_t`|The size of the destination buffer including the terminating NUL|
+|**`occurrence`**|`size_t`|The instance index of the wanted variable|
 
 ### Return Value
 
 | Type | Description |
 | :--- | :--- |
-|`int`||
+|`int`|Length of the variable contents, or an error code|
 
 ### Description
 
+The function `mg_get_var2()` can be used to return the contents of a variable passed to the server as either POST data, or in the URI in a GET call. The function is somilar to [`mg_get_var()`](mg_get_var.md) but the difference is that `mg_get_var2()` can be used if the same variable is present multiple times in the data. The `occurence` parameter is used to identify which instance of the variable must be returned where **`0`** is used for the first variable with the specified name, **`1`** for the second and so on.
+
+The function returns the length of the variable content in the return buffer, **`-1`** if a variable with the specified name could not be found and **`-2`** if the pointer to the result buffer is NULL, the size of the result buffer is zero or when the result buffer is too small to contain the variable content and terminating NUL.
+
 ### See Also
 
 * [`mg_get_cookie();`](mg_get_cookie.md)

docs/api/mg_handle_form_request.md

@@ -6,17 +6,19 @@
 
 | Parameter | Type | Description |
 | :--- | :--- | :--- |
-|**`conn`**|`struct mg_connection *`||
-|**`fdh`**|`struct mg_form_data_handler`|
+|**`conn`**|`struct mg_connection *`|The connection on which form data must be processed|
+|**`fdh`**|`struct mg_form_data_handler`|Structure with callback functions to to the heavy work|
 
 ### Return Value
 
 | Type | Description |
 | :--- | :--- |
-|`int`||
+|`int`|The number of fields processed, or an error code|
 
 ### Description
 
+The function `mg_handle_form_request()` processes form data on a connection. The function uses callback functions for the heavy lifting which are passed to the function as fields in a [`struct mg_form_data_handler`](mg_form_data_handler.md) structure. The number of processed fields is returned by the function, or a negative value when an error occured. I nthe situation where some fields are processed successfully (for example file downloads) and an error occurs later in the form processing, the function still returns a negative value. It is the responsibility of the calling party to do the necessary cleanup. The calling party should also do the cleanup of any files which are created, but not required anymore later.
+
 ### See Also
 
-* [`struct mg_form_data_handler;`](mg_form_data_handler)
+* [`struct mg_form_data_handler;`](mg_form_data_handler.md)

docs/api/mg_header.md

@@ -11,7 +11,8 @@
 
 ### Description
 
-The structure `mg_header` is used as a sub-structure in the `mg_request_info` structure to
-store the name and value of one HTTP request header as sent by the client.
+The structure `mg_header` is used as a sub-structure in the [`struct mg_request_info;`](mg_request_info.md) structure to store the name and value of one HTTP request header as sent by the client.
 
 ### See Also
+
+* [`struct mg_request_info;`](mg_request_info.md)

docs/api/mg_lock_connection.md

@@ -5,7 +5,7 @@
 ### Parameters
 
 | Parameter | Type | Description |
-|**`conn`**|`struct mg_connection *`||
+|**`conn`**|`struct mg_connection *`|The connection to retrieve a lock|
 
 ### Return Value
 
@@ -13,6 +13,8 @@
 
 ### Description
 
+The function `mg_lock_connection()` is specifically for websocket connections to lock connection. Using this function in combination with [`mg_unlock_connection();`](mg_unlock_connection.md) is necessary around [`mg_write()`](mg_write.md) and [`mg_printf()`](mg_printf.md) calls if the code has server-initiated communication, as well as with communication in direct response to a message.
+
 ### See Also
 
 * [`mg_lock_context();`](mg_lock_context.md)

docs/api/mg_lock_context.md

@@ -6,7 +6,7 @@
 
 | Parameter | Type | Description |
 | :--- | :--- | :--- |
-|**`ctx`**|`struct mg_context *`||
+|**`ctx`**|`struct mg_context *`|The context to put the lock on|
 
 ### Return Value
 
@@ -14,6 +14,8 @@
 
 ### Description
 
+The function `mg_lock_context()` can be used to acquire a lock for exclusive access to resources which are shared between connection of threads. The lock is context wide. The lock must be released with a call to [`mg_unlock_context()`](mg_unlock_context.md).
+
 ### See Also
 
 * [`mg_lock_connection();`](mg_lock_connection.md)

docs/api/mg_md5.md

@@ -6,15 +6,19 @@
 
 | Parameter | Type | Description |
 | :--- | :--- | :--- |
-|**`buf`**|`char[33]`||
-|**`...`**|*various*||
+|**`buf`**|`char[33]`|Storage buffer for the calculated MD5 sum|
+|**`...`**|`char *, ...`|NULL terminated list of pointers to strings with data|
 
 ### Return Value
 
 | Type | Description |
 | :--- | :--- |
-|`char *`||
+|`char *`|Pointer to the resulting MD5 string|
 
 ### Description
 
+The function `mg_md5()` caluclates the MD5 checksum of a NULL terminated list of NUL terminated ASCII strings. The MD5 checksum is returned in human readable format as an MD5 string in a caller supplied buffer.
+
+The function returns a pointer to the supplied result buffer.
+
 ### See Also