Merge branch 'discovery' of chicago.everbase.net:meshlink/meshlink into everbase

[meshlink] / src / meshlink.h

diff --git a/src/meshlink.h b/src/meshlink.h
index c80cd228a19d8d16e79e3693a059fe2956af05ad..335714cbc7f78fc75a4f9f68d3666639634ab7da 100644 (file)
--- a/src/meshlink.h
+++ b/src/meshlink.h
@@ -221,7 +221,7 @@ typedef enum {
 } meshlink_log_level_t;
 
 /// A callback for receiving log messages generated by MeshLink.
-/** @param mesh      A handle which represents an instance of MeshLink.
+/** @param mesh      A handle which represents an instance of MeshLink, or NULL.
  *  @param level     An enum describing the severity level of the message.
  *  @param text      A pointer to a nul-terminated C string containing the textual log message.
  *                   This pointer is only valid for the duration of the callback.
@@ -232,12 +232,21 @@ typedef void (*meshlink_log_cb_t)(meshlink_handle_t *mesh, meshlink_log_level_t
 
 /// Set the log callback.
 /** This functions sets the callback that is called whenever MeshLink has some information to log.
- *  The callback is run in MeshLink's own thread.
+ *
+ *  The @a mesh @a parameter can either be a valid MeshLink handle, or NULL.
+ *  In case it is NULL, the callback will be called for errors that happen outside the context of a valid mesh instance.
+ *  Otherwise, it will be called for errors that happen in the context of the given mesh instance.
+ *
+ *  If @a mesh @a is not NULL, then the callback is run in MeshLink's own thread.
  *  It is important that the callback uses apprioriate methods (queues, pipes, locking, etc.)
  *  to hand the data over to the application's thread.
  *  The callback should also not block itself and return as quickly as possible.
  *
- *  @param mesh      A handle which represents an instance of MeshLink.
+ *  The @a mesh @a parameter can either be a valid MeshLink handle, or NULL.
+ *  In case it is NULL, the callback will be called for errors that happen outside the context of a valid mesh instance.
+ *  Otherwise, it will be called for errors that happen in the context of the given mesh instance.
+ *
+ *  @param mesh      A handle which represents an instance of MeshLink, or NULL.
  *  @param level     An enum describing the minimum severity level. Debugging information with a lower level will not trigger the callback.
  *  @param cb        A pointer to the function which will be called when another node sends data to the local node.
  *                   If a NULL pointer is given, the callback will be disabled.