[svn-commits] eliel: branch group/data_api_gsoc2009 r210770 - in /team/group/data_api_gsoc2...

[SVN commits to the Digium repositories]

Author: eliel
Date: Wed Aug  5 21:13:32 2009
New Revision: 210770

URL: http://svn.asterisk.org/svn-view/asterisk?view=rev&rev=210770
Log:
Add more documentation.


Modified:
    team/group/data_api_gsoc2009/include/asterisk/data.h
    team/group/data_api_gsoc2009/main/data.c

Modified: team/group/data_api_gsoc2009/include/asterisk/data.h
URL: http://svn.asterisk.org/svn-view/asterisk/team/group/data_api_gsoc2009/include/asterisk/data.h?view=diff&rev=210770&r1=210769&r2=210770
==============================================================================
--- team/group/data_api_gsoc2009/include/asterisk/data.h (original)
+++ team/group/data_api_gsoc2009/include/asterisk/data.h Wed Aug  5 21:13:32 2009
@@ -33,6 +33,10 @@
  *
  * \section USAGE
  *
+ * \subsection Provider
+ *
+ * \b Register
+ *
  * To register a callback use:
  *
  * \code
@@ -63,17 +67,67 @@
  *	ast_data_register_multiple(list_providers, ARRAY_LEN(list_providers));
  * \endcode
  *
+ * \b Unregister
+ *
  * To unregister a callback function already registered you can just call:
  *
  * \code
  *	ast_data_unregister(NULL);
  * \endcode
  * And every node registered by the current module (file) will be unregistered.
- * If you want to unregister an specific node use:
+ * If you want to unregister a specific node use:
  *
  * \code
  *	ast_data_unregister("/node/path");
  * \endcode
+ *
+ * \b Implementation
+ *
+ * A simple callback function implementation:
+ *
+ * \code
+ *	#include <data.h>
+ *
+ *
+ * 	struct test_structure {
+ * 		int a;
+ * 		double b;
+ * 	};
+ *
+ *	DATA_EXPORT_TEST_STRUCTURE(MEMBER)			\
+ *		MEMBER(test_structure, a, AST_DATA_INTEGER)	\
+ *		MEMBER(test_structure, b, AST_DATA_DOUBLE)
+ *
+ *	AST_DATA_STRUCTURE(test_structure, DATA_EXPORT_TEST_STRUCTURE)
+ *
+ *	static int my_callback_function(struct ast_data_search *search,
+ *		struct ast_data *root_node)
+ *	{
+ *		struct ast_data *internal_node;
+ *		struct test_structure ts = {
+ *			.a = 10,
+ *			.b = 20
+ *		};
+ *
+ *		if (ast_data_search_cmp_structure(search, test_structure, "test_node")) {
+ *			return 0;
+ *		}
+ *
+ *		internal_node = ast_data_add_node(root_node, "test_node");
+ *		if (!internal_node) {
+ *			return -1;
+ *		}
+ *
+ *		ast_data_add_structure(test_structure, internal_node, ts);
+ *
+ *		return 0;
+ *	}
+ *
+ * \endcode
+ *
+ * \subsection Get
+ *
+ * \b Getting \b the \b tree
  *
  * To get the tree you need to create a query, a query is based on three parameters
  * a path to the provider, a search condition and a filter condition.
@@ -93,6 +147,8 @@
  *	ast_data_free(result);
  * \endcode
  *
+ * \b Iterate
+ *
  * To retrieve nodes from the tree, it is possible to iterate through the returned
  * nodes of the tree using:
  * \code
@@ -107,6 +163,8 @@
  * \endcode
  * node_name is the name of the nodes to retrieve and path is the path to the internal
  * nodes to retrieve (if needed).
+ *
+ * \b Retrieving
  *
  * After getting the node you where searching for, you will need to retrieve its value,
  * to do that you may use one of the ast_data_retrieve_##type functions:
@@ -119,6 +177,7 @@
  *	unsigned int f = ast_data_retrieve_uint(tree, "path/to/the/node");
  *	void *g = ast_data_retrieve_ptr(tree, "path/to/the/node");
  * \endcode
+ *
  */
 
 #if defined(__cplusplus) || defined(c_plusplus)
@@ -152,6 +211,7 @@
 
 /*! \brief structure retrieved from a node, with the nodes content. */
 struct ast_data_retrieve {
+	/*! \brief The type of the node retrieved. */
 	enum ast_data_type type;
 
 	union {
@@ -166,6 +226,9 @@
 	} value;
 };
 
+/*!
+ * \brief The get callback definition.
+ */
 typedef int (*ast_data_get_cb)(const struct ast_data_search *search,
 	struct ast_data *root);
 typedef int *(*ast_data_put_cb)(void);

Modified: team/group/data_api_gsoc2009/main/data.c
URL: http://svn.asterisk.org/svn-view/asterisk/team/group/data_api_gsoc2009/main/data.c?view=diff&rev=210770&r1=210769&r2=210770
==============================================================================
--- team/group/data_api_gsoc2009/main/data.c (original)
+++ team/group/data_api_gsoc2009/main/data.c Wed Aug  5 21:13:32 2009
@@ -2291,6 +2291,7 @@
 }
 
 /*!
+ * \internal
  * \brief One color for each node type.
  */
 static const struct {
@@ -2311,7 +2312,7 @@
  * \internal
  * \brief Get the color configured for a specific node type.
  * \param[in] type The node type.
- * \retval The color specified for the passed type.
+ * \returns The color specified for the passed type.
  */
 static int data_result_get_color(enum ast_data_type type)
 {
@@ -2557,6 +2558,7 @@
 }
 
 /*!
+ * \internal
  * \brief Handle CLI command "data show providers"
  */
 static char *handle_cli_data_show_providers(struct ast_cli_entry *e, int cmd,