* document source api

src/sources/source.h

@@ -14,16 +14,121 @@
 
 #include "../strlcpy.h"
 
+/**
+ * @file
+ * This header describes module API of type 'source'
+ *
+ * Sample workflow of module usage:
+ *
+ * @msc
+ *   f2b, source;
+ *   f2b =>  source [label="create(init)"];
+ *   f2b <<  source [label="module handler, cfg_t *cfg"];
+ *       |||;
+ *   f2b =>  source [label="config(cfg, param, value)"];
+ *   f2b <<  source [label="true"];
+ *   f2b =>  source [label="config(cfg, param, value)"];
+ *   f2b <<  source [label="true"];
+ *   f2b =>  source [label="config(cfg, param, value)"];
+ *   f2b <<  source [label="false"];
+ *   f2b =>  source [label="error(cfg)"];
+ *   f2b <<  source [label="const char *error"];
+ *       |||;
+ *   f2b =>  source [label="errcb(cfg, cb), optional"];
+ *       |||;
+ *   f2b =>  source [label="ready(cfg)"];
+ *   f2b <<  source [label="true"];
+ *       ---        [label="source is ready for start()"];
+ *   f2b =>  source [label="start()"];
+ *   f2b <<  source [label="true"];
+ *       ---        [label="source is ready to use"];
+ *   f2b =>  source [label="next(cfg, buf, sizeof(buf), true)"];
+ *   f2b <<  source [label="false"];
+ *       ...        [label="no data this time, try later"];
+ *   f2b =>  source [label="next(cfg, buf, sizeof(buf), true)"];
+ *   f2b <<  source [label="true"];
+ *   f2b =>  source [label="next(cfg, buf, sizeof(buf), false)"];
+ *   f2b <<= source [label="errcb(char *error)"];
+ *   f2b <<  source [label="true"];
+ *   f2b =>  source [label="next(cfg, buf, sizeof(buf), false)"];
+ *   f2b <<  source [label="false"];
+ *       ...        [label="time passed"];
+ *   f2b =>  source [label="stop(cfg)"];
+ *   f2b <<  source [label="true"];
+ *       ---        [label="now you may config(), start() or destroy() source"];
+ *   f2b =>  source [label="destroy(cfg)"];
+ * @endmsc
+ */
+
+/**
+ * @def INIT_MAX
+ * Defines max length of @a init param in @a create()
+ */
 #define INIT_MAX 256
 
+/**
+ * Opaque module handler, contains module internal structs
+ */
 typedef struct _config cfg_t;
-
+/**
+ * @brief Create instance of module
+ * @param init Module-specific init string
+ * @returns Opaque module handler or NULL on failure
+ */
 extern cfg_t *create(const char *init);
-extern bool   config(cfg_t *c, const char *key, const char *value);
-extern bool    ready(cfg_t *c);
-extern char   *error(cfg_t *c);
-extern void    errcb(cfg_t *c, void (*cb)(char *errstr));
-extern bool    start(cfg_t *c);
-extern bool     next(cfg_t *c, char *buf, size_t bufsize, bool reset);
-extern bool     stop(cfg_t *c);
-extern void  destroy(cfg_t *c);
+/**
+ * @brief Configure module instance
+ * @param cfg Module handler
+ * @param key Parameter name
+ * @param value Parameter value
+ * @returns true on success, false on error with setting intenal error buffer
+ */
+extern bool   config(cfg_t *cfg, const char *key, const char *value);
+/**
+ * @brief Checks is module ready for usage
+ * @param cfg Module handler
+ * @returns true if ready, false if not
+ */
+extern bool    ready(cfg_t *cfg);
+/**
+ * @brief Returns last error description
+ * @param cfg Module handler
+ * @returns Pointer to string with description of last error
+ * @note Returned pointer not marked with const, because libdl complains,
+ *       but contents on pointer should not be modified or written in any way
+ */
+extern char   *error(cfg_t *cfg);
+/**
+ * @brief Sets the error callback for use in processing
+ * @param cfg Module handler
+ * @param cb Error callback
+ * @note Optional, if this function is not called, processing errors will be suppressed
+ */
+extern void    errcb(cfg_t *cfg, void (*cb)(char *errstr));
+/**
+ * @brief Allocate resources and start processing
+ * @param cfg Module handler
+ * @returns true on success, false on error with setting intenal error buffer
+ */
+extern bool    start(cfg_t *cfg);
+/**
+ * @brief Poll source for new data
+ * @param cfg Module handler
+ * @param buf Pointer to buffer for storing result
+ * @param bufsize Size of buffer above (in bytes)
+ * @param reset Reset internals to start of list
+ * @returns false if no new data available, or true otherwise with filling @a buf
+ */
+extern bool     next(cfg_t *cfg, char *buf, size_t bufsize, bool reset);
+/**
+ * @brief Deallocate resources, prepare for module destroy
+ * @param cfg Module handler
+ * @returns true on success
+ */
+extern bool     stop(cfg_t *cfg);
+/**
+ * @brief Free module handle
+ * @param cfg Module handler
+ * @note Module handler becomes invalid after calling this function on it
+ */
+extern void  destroy(cfg_t *cfg);