Added descriptions in API Reference

docs/api/client_cert.md

@@ -13,8 +13,7 @@
 
 ### Description
 
-The structure `client_cert` is used as a sub-structure in the [`mg_request_info`](mg_request_info.md)
-structure to store information of an optional client supplied certificate.
+The structure `client_cert` is used as a sub-structure in the [`mg_request_info`](mg_request_info.md) structure to store information of an optional client supplied certificate.
 
 ### See Also
 

docs/api/mg_callbacks.md

@@ -50,12 +50,9 @@
 
 ### Description
 
-A pointer to a `mg_callbacks` structure is passed as parameter to the [`mg_start()`](mg_start.md)
-function to
-provide links to callback functions which the webserver will call at specific events. If a
-specific callback function is not supplied, CivetWeb will fallback to default internal callback
-routines. Callback functions give the application detailed control over how specific events
-should be handled.
+Much of the functionality in the Civetweb library is provided through callback functions. The application registers their own processing functions with the Civetweb library and when an event happens, the appropriate callback function is called. In this way an application is able to have their processing code right at the heart of the webserver, without the need to change the code of the webserver itself. A number of callback functions are registered when the civetweb subsystem is started. Other may be added or changed at runtime with helper functions.
+
+A pointer to a `mg_callbacks` structure is passed as parameter to the [`mg_start()`](mg_start.md) function to provide links to callback functions which the webserver will call at specific events. If a specific callback function is not supplied, CivetWeb will fallback to default internal callback routines. Callback functions give the application detailed control over how specific events should be handled.
 
 ### See Also
 

docs/api/mg_check_feature.md

@@ -16,12 +16,7 @@
 
 ### Description
 
-The function `mg_check_feature()` can be called from an application program to
-check of specific features have been compiled in the civetweb version which the
-application has been linked to. The feature to check is provided as an unsigned
-integer parameter. If the function is available in the currently linked library
-version, a value **> 0** is returned. Otherwise the function `mg_check_feature()`
-returns the value **0**.
+The function `mg_check_feature()` can be called from an application program to check of specific features have been compiled in the civetweb version which the application has been linked to. The feature to check is provided as an unsigned integer parameter. If the function is available in the currently linked library version, a value **> 0** is returned. Otherwise the function `mg_check_feature()` returns the value **0**.
 
 The following parameter values can be used:
 
@@ -36,7 +31,7 @@ The following parameter values can be used:
 | **64** | USE_DUKTAPE | *Support for server side JavaScript*. Server side JavaScript can be used for dynamic page generation if the proper options have been set at compile time. Please note that client side JavaScript execution is always available if it has been enabled in the connecting browser. |
 | **128** | NO_CACHING | *Support for caching*. The webserver will support caching, if it has not been disabled while compiling the library. |
 
-Parameter values other than the values mentioned above will give undefined results.
+Parameter values other than the values mentioned above will give undefined results. Therefore—although the parameter values for the `mg_check_feature()` function are effectively bitmasks, you should't assume that combining two of those values with an OR to a new value will give any meaningful results when the function returns.
 
 ### See Also
 

docs/api/mg_client_options.md

@@ -13,10 +13,9 @@
 
 ### 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).
+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). Please note that IPv6 addresses are only permitted if IPv6 support was enabled during compilation. You can use the function [`mg_check_feature()`](mg_check_feature.md) with the parameter `USE_IPV6` while running your application to check if IPv6 is supported.
 
 ### See Also
 
+* [`mg_check_feature();`](mg_check_feature.md)
 * [`mg_connect_client_secure();`](mg_connect_client_secure.md)

docs/api/mg_close_connection.md

@@ -14,9 +14,7 @@
 
 ### 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.
+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
 

docs/api/mg_connect_client.md

@@ -20,11 +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.
-
+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 pointer to a connection structure when the connection is established and NULL otherwise. The host may be on IPv4 or IPv6, but IPv6 is not enabled in every Civetweb installation. Specifically the use of IPv6 communications has to be enabled when the library is compiled. At runtime you can use the [`mg_check_feature()`](mg_check_feature.md) function with the parameter `USE_IPV6` to check if IPv6 communication is supported.
+ 
 ### See Also
 
+* [`mg_check_feature();`](mg_check_feature.md)
 * [`mg_connect_client_secure();`](mg_connect_client_secure.md)
 * [`mg_connect_websocket_client();`](mg_connect_websocket_client.md)

docs/api/mg_connect_client_secure.md

@@ -18,13 +18,13 @@
 
 ### 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.
+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 a `struct mg_connection` structure when successful and NULL otherwise.
+
+Please note that IPv6 communication is supported by Civetweb, but only if the use of IPv6 was enabled at compile time. The check while running a program if IPv6 communication is possible you can call [`mg_check_feature()`](mg_check_feature.md) with the `USE_IPV6` parameter to check if IPv6 communications can be used.
 
 ### See Also
 
 * [`struct mg_client_options;`](mg_client_options.md)
+* [`mg_check_feature();`](mg_check_feature.md)
 * [`mg_connect_client();`](mg_connect_client.md)
 * [`mg_connect_websocket_client();`](mg_connect_websocket_client.md)

docs/api/mg_connect_websocket_client.md

@@ -25,11 +25,12 @@
 
 ### 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.
+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.
+
+Civetweb supports both IPv4 and IPv6 communication, but only if the use if IPv6 has been enabled at compile time. When running an application it is possible to check if IPv6 addressing is available by calling the [`mg_check_feature()`](mg_check_feature.md) function with the `USE_IPV6` parameter.
 
 ### See Also
 
+* [`mg_check_feature();`](mg_check_feature.md)
 * [`mg_connect_client();`](mg_connect_client.md)
 * [`mg_connect_client_secure();`](mg_connect_client_secure.md)

docs/api/mg_cry.md

@@ -16,11 +16,7 @@
 
 ### 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.
+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
 

docs/api/mg_download.md

@@ -22,19 +22,16 @@
 
 ### 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 `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:
+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" );`
 
+Please note that although Civetweb supports both IPv4 and IPv6 communication that IPv6 addressing is only available if it was enabled at compile time. When running an application it is possible to check if IPv6 support has been compiled in by using the [`mg_check_feature()`](md_check_feature.md) function with the parameter `USE_IPV6`.
+
 ### See Also
 
+* [`mg_check_feature();`](mg_check_feature.md)
 * [`mg_close_connection();`](mg_close_connection.md)

docs/api/mg_form_data_handler.md

@@ -4,15 +4,29 @@
 
 ### Fields
 
-| Field | Type | Description |
-| :--- | :--- | :--- |
-|**`field_found`**|||
-|**`field_get`**|||
-|**`field_store`**|||
-|**`user_data`**|||
+|Field|Description|
+|:---|:---|
+|**`field_found`**|**`int field_found( const char *key, const char *filename, char *path, size_t pathlen, void *user_data )`**;|
+||The callback function `field_found()` is called when a new field has been found. The return value of this callback is used to define how the field should be processed. The parameters contain the following information:|
+||**`key`** - The name of the field as it was named with the `name` tag in the HTML source.|
+||**`filename`** - The name of the file to upload. Please not that this parameter is only valid when the input type was set to `file`. Otherwise this parameter has the value `NULL`.|
+||**`path`** - This is an output parameter used to store the full name of the file including the path to store an incoming file at the computer. This parameter must be provided by the application to Civetweb when a form field of type `file` is found. Please not that together with setting this parameter, the callback function must return `FORM_FIELD_STORAGE_STORE`.i With any other return value the contents of the `path` buffer is ignored by Civetweb.|
+||**`pathlen`** - The length of the buffer where the output path can be stored.|
+||**`user_data`** - A pointer to the value of the field `user_data` of the structure `struct mg_form_data_handler`.|
+||The callback function `field_found()` can return the following values back to Civetweb:|
+||**`FORM_FIELD_STORAGE_SKIP`** - Ignore the field and continue with processing the next field|
+||**`FORM_FIELD_STORAGE_GET`** - Call the callback function `field_get()` to receive the form data|
+||**`FORM_FIELD_STORAGE_STORE`** - Store a file as `path` and overwrite that file if it already exists|
+||**`FORM_FIELD_STORAGE_ABORT`** - Stop parsing the request and ignore all remaining form fields|
+|**`field_get`**|**`int field_get( const char *key, const char *value, size_t valuelen, void *user_data );`**|
+|**`field_store`**|**`int field_store( const char *path, long long file_size, void *user_data );`**|
+|**`user_data`**|**`void *`**|
+||The `user_data` field is a user supplied argument that will be passed as parameter to each of callback functions|
 
 ### Description
 
+The structure `struct mg_form_data_handler` contains callback functions for handling form fields. Form fields give additional information back from a web page to the server which can be processed by these callback functions.
+
 ### See Also
 
 * [`mg_handle_form_request();`](mg_handle_form_request.md)