add extended debug log docs

Author: martinwag

docs/index.md

@@ -249,6 +249,16 @@ The *modbus_strerror()* function is provided to translate libmodbus-specific
 error codes into error message strings; for details refer to
 [modbus_strerror](modbus_strerror.md).
 
+## Extended debug
+
+By default, the debug output created by enabling [modbus_set_debug](modbus_set_debug.md)
+is written to stdout/stderr. With the following functions those can be redirected
+to files or a callback.
+
+- [modbus_set_out_user_data](modbus_set_out_user_data.md)
+- [modbus_set_error_user_data](modbus_set_error_user_data.md)
+- [modbus_set_trace_handler](modbus_set_trace_handler.md)
+
 ## Miscellaneous
 
 To deviate from the Modbus standard, you can enable or disable quirks with:

docs/modbus_set_error_user_data.md

@@ -0,0 +1,32 @@
+# modbus_set_error_user_data
+
+## Name
+
+modbus_set_error_user_data - set file stream to write log output
+
+## Synopsis
+
+```c
+void modbus_set_error_user_data(modbus_t *ctx, void* out_user_data);
+```
+
+## Description
+
+The *modbus_set_error_user_data()* changes where log output is written
+to when enabled with [modbus_set_debug](modbus_set_debug.md). Defaults
+to stderr when not set.
+
+
+## Example
+
+```c
+FILE *fp;
+fp = fopen("error.txt", "w");
+modbus_set_error_user_data(ctx, fp);
+modbus_set_debug(ctx, 1)
+```
+
+## See also
+
+- [modbus_set_out_user_data](modbus_set_out_user_data.md)
+- [modbus_set_trace_handler](modbus_set_trace_handler.md)

docs/modbus_set_out_user_data.md

@@ -0,0 +1,32 @@
+# modbus_set_out_user_data
+
+## Name
+
+modbus_set_out_user_data - set file stream to write log output
+
+## Synopsis
+
+```c
+void modbus_set_out_user_data(modbus_t *ctx, void* out_user_data);
+```
+
+## Description
+
+The *modbus_set_out_user_data()* changes where log output is written
+to when enabled with [modbus_set_debug](modbus_set_debug.md). Defaults
+to stdout when not set.
+
+
+## Example
+
+```c
+FILE *fp;
+fp = fopen("output.txt", "w");
+modbus_set_out_user_data(ctx, fp);
+modbus_set_debug(ctx, 1)
+```
+
+## See also
+
+- [modbus_set_error_user_data](modbus_set_error_user_data.md)
+- [modbus_set_trace_handler](modbus_set_trace_handler.md)

docs/modbus_set_trace_handler.md

@@ -0,0 +1,44 @@
+# modbus_set_trace_handler
+
+## Name
+
+modbus_set_trace_handler - call method when log data is written
+
+## Synopsis
+
+```c
+typedef int (*modbus_stream_handler_t)(void *user, const char *format, va_list ap);
+void modbus_set_trace_handler(modbus_t *ctx, modbus_stream_handler_t handler);
+```
+
+## Description
+
+The *modbus_set_trace_handler()* sets a callback. When log data is written, the 
+callback is called. A log message is finalized with a '\n' as last character. 
+Defaults to vfprintf when not set.
+
+
+## Example
+
+```c++
+class Test {
+  public:
+    static int log_callback(void *user, const char *format, va_list ap)
+    {
+        auto *inst = reinterpret_cast<Test*>(user);
+        //call methods
+    }
+    void setup()
+    {
+        modbus_set_out_user_data(reinterpret_cast<void*>(this));
+        modbus_set_error_user_data(reinterpret_cast<void*>(this));
+        modbus_set_trace_handler(log_callback);
+        modbus_set_debug(true);
+    }
+}
+```
+
+## See also
+
+- [modbus_set_out_user_data](modbus_set_out_user_data.md)
+- [modbus_set_error_user_data](modbus_set_error_user_data.md)