[svn-commits] eliel: branch eliel/data_retrieval r183692 - /team/eliel/data_retrieval/main/

[SVN commits to the Digium repositories]

Author: eliel
Date: Mon Mar 23 09:51:47 2009
New Revision: 183692

URL: http://svn.digium.com/svn-view/asterisk?view=rev&rev=183692
Log:
More doxygen documentation

Modified:
    team/eliel/data_retrieval/main/data.c

Modified: team/eliel/data_retrieval/main/data.c
URL: http://svn.digium.com/svn-view/asterisk/team/eliel/data_retrieval/main/data.c?view=diff&rev=183692&r1=183691&r2=183692
==============================================================================
--- team/eliel/data_retrieval/main/data.c (original)
+++ team/eliel/data_retrieval/main/data.c Mon Mar 23 09:51:47 2009
@@ -50,12 +50,14 @@
 /*!
  * \internal
  * \brief asterisk data locking mechanism.
+ * \see root_data
  */
 static ast_rwlock_t root_data_lock;
 
 /*!
  * \internal
  * \brief Common string hash function.
+ * \see ast_data_init
  */
 static int data_node_hash(const void *obj, const int flags)
 {
@@ -67,6 +69,7 @@
 /*!
  * \internal
  * \brief Compare two data_node's.
+ * \see ast_data_init
  */
 static int data_node_cmp(void *obj, void *arg, int flags)
 {
@@ -79,6 +82,7 @@
 /*!
  * \internal
  * \brief Lock the data registered handlers structure for writing.
+ * \see data_unlock
  */
 static void data_write_lock(void)
 {
@@ -88,6 +92,7 @@
 /*!
  * \internal
  * \brief Lock the data registered handlers structure for reading.
+ * \see data_unlock
  */
 static void data_read_lock(void)
 {
@@ -107,6 +112,9 @@
  * \internal
  * \brief Get the next node name in a path (/node1/node2)
  *        Avoid null nodes like //node1//node2/node3.
+ * \param path The path where we are going to search for the next node name.
+ * \retval The next node name we found inside the given path.
+ * \retval NULL if there are no more node names.
  */
 static char *next_node_name(char **path)
 {
@@ -158,6 +166,8 @@
  * \brief Add a child node named 'name' to the 'parent' node.
  * \param parent Where to add the child node.
  * \param name The name of the child node.
+ * \retval NULL on error.
+ * \retval A newly allocated child in parent.
  */
 static struct data_node *data_node_add_child(struct ao2_container *parent, const char *name)
 {
@@ -180,6 +190,7 @@
  * \param name The node name to find.
  * \retval NULL if a node wasn't found.
  * \retval The node found.
+ * \note Remember to decrement the ref count of the returned node after using it.
  */
 static struct data_node *data_find_child(struct ao2_container *parent, const char *name)
 {
@@ -203,6 +214,7 @@
  * \param path The path of nodes to release.
  * \retval < 0 on error.
  * \retval 0 on success.
+ * \see data_nodes_create
  */
 static int data_nodes_release(struct ao2_container *parent, const char *path)
 {
@@ -245,6 +257,7 @@
  * \brief Create the middle nodes for the specified path (asterisk/testnode1/childnode)
  * \param parent Where to add the middle nodes structure.
  * \param path The path of nodes to add.
+ * \see data_nodes_release
  */
 static struct data_node *data_nodes_create(struct ao2_container *parent, const char *path)
 {