Logging library: better API documentation

Author: ryzhyk

lib/ddlog_log.h

@@ -8,7 +8,8 @@
  * `module`    - Opaque module identifier.  Can represent module, subsystem, log
  *               stream, etc.
  * `cb`        - Callback to be invoked for each log message with the given module
- *               id and log level `<= max_level`.
+ *               id and log level `<= max_level`.  Passing `NULL` disables
+ *               logging for the given module.
  * `max_level` - Don't invoke the callback for messages whoe log level is
  *               `> max_level`.
  */

lib/log.dl

@@ -84,6 +84,7 @@ typedef log_level_t = signed<32>
  * `level`  - log level
  * `msg`    - error message (UTF-8)
  *
- * Always returns `true`.
+ * This function returns a `bool` so that it can be used as a filter inside
+ * DDlog rules.  It always returns `true`.
  */
 extern function log(module: module_t, level: log_level_t, msg: string): bool

lib/log.rs

@@ -15,6 +15,7 @@ lazy_static! {
 
 /*
  * Logging API exposed to the DDlog program.
+ * (see detailed documentation in `log.dl`)
  */
 pub fn log_log(module: &log_module_t, level: &log_log_level_t, msg: &String) -> bool
 {
@@ -27,7 +28,10 @@ pub fn log_log(module: &log_module_t, level: &log_log_level_t, msg: &String) ->
 }
 
 /*
- * Configuration API.
+ * Configuration API
+ * (detailed documentation in `ddlog_log.h`)
+ *
+ * `cb = None` - disables logging for the given module.
  *
  * NOTE: we set callback and log level simultaneously.  A more flexible API
  * would allow changing log level without changing the callback.