Comment use of "const" for handles (mg_context*,mg_connection*)

The two opaque pointers "struct mg_context *" and "struct mg_connection *"
are used as handles. A "const" attribute for mg_context means "dont modify
the running server", while "dont modify the connection" basically means
"dont read/write data".
Add some documentation for this, also taking #452 into account.

docs/APIReference.md

@@ -5,7 +5,8 @@ A C API is available to integrate the CivetWeb functionality in a larger
 codebase. A C++ wrapper is also available, although it is not guaranteed
 that all functionality available through the C API can also be accessed
 from C++. This document describes the public C API. Basic usage examples of
-the API can be found in [Embedding.md](Embedding.md).
+the API can be found in [Embedding.md](Embedding.md), as well as in the
+examples directory.
 
 ## Macros
 
@@ -16,6 +17,17 @@ the API can be found in [Embedding.md](Embedding.md).
 | **`CIVETWEB_VERSION_MINOR`** | The current minor version as number, e.g., (9) for version 1.9. |
 | **`CIVETWEB_VERSION_PATCH`** | The current patch version as number, e.g., (0) for version 1.9 or (1) for version 1.9.1. |
 
+## Handles
+
+* `struct mg_context *`
+Handle for one instance of the HTTP(S) server.
+All functions using `const struct mg_context *` as an argument do not modify a running server instance, but just query information. Functions using a non-const `struct mg_context *` as an argument may modify a server instance (e.g., register a new URI, stop the server, ...).
+
+* `struct mg_connection *`
+Handle for one individual client-server connection.
+Functions working with `const struct mg_connection *` operate on data already known to the server without reading data from or sending data to the client. Callbacks using a `const struct mg_connection *` argument are supposed to not call functions from the `mg_read()` and `mg_write()` family. To support a correct application, reading and writing functions require a non-const `struct mg_connection *` connection handle.
+
+The content of both structures is not defined in the interface - they are only used as opaque pointers (handles).
 
 ## Structures
 
@@ -112,3 +124,5 @@ the API can be found in [Embedding.md](Embedding.md).
 
 * [~~`mg_get_valid_option_names();`~~](api/mg_get_valid_option_names.md)
 * [~~`mg_upload( conn, destination_dir );`~~](api/mg_upload.md)
+
+

docs/api/mg_set_user_connection_data.md

@@ -15,8 +15,30 @@
 
 ### Description
 
-The function `mg_set_user_connection_data()` can be used to add or change the user data pointer attached to a connection. Using the value NULL in the call will remove a previously assigned user data pointer.
+The function `mg_set_user_connection_data()` can be used to set a user defined
+data pointer attached to a connection.  This value can be read using 
+`mg_get_user_connection_data()`.
+Any call to `mg_set_user_connection_data()` will overwrite a previously
+assigned user data pointer.
+
+`mg_set_user_connection_data()` requires a non-const 
+`struct mg_connection *` to set the user data pointer.  It is save to use the
+`const struct mg_connection *` passed to a websocket connect handler (with a
+const cast), since `const` just means you must not use `mg_read()` or
+`mg_write()` in this context.
+
+Alternatively, you can use the `init_connection` callback in 
+`struct mg_callbacks` to set the user data pointer.
+In this case, typically `init_connection` is used to allocate memory for
+a user defined `struct`, while `connection_close` is used to free this
+memory again.
+
 
 ### See Also
 
-* [`mg_get_user_connection_data();`](mg_user_connection_data.md)
+* [`mg_get_user_connection_data();`](mg_get_user_connection_data.md)
+* [`struct mg_callbacks`](mg_callbacks.md)
+* [`mg_set_websocket_handler();`](mg_set_websocket_handler.md)
+* [`mg_read();`](mg_read.md)
+* [`mg_write();`](mg_write.md)
+