Add documentation to the public API.

1 files changed, 306 insertions, 26 deletions

diff --git a/include/plist/plist.h b/include/plist/plist.h
index 76ce0ec..2c0df11 100644
--- a/include/plist/plist.h
+++ b/include/plist/plist.h
@@ -29,72 +29,352 @@ extern "C" {
 #include <stdint.h>
 #include <sys/types.h>
 
+/**
+ * \mainpage libplist : A library to handle Apple Property Lists
+ * \defgroup PublicAPI Public libplist API
+ */
+/*@{*/
+
+
+/**
+ * The basic plist abstract data type.
+ */
 typedef void* plist_t;
 
+/**
+ * The enumeration of plist node types.
+ */
 typedef enum {
-        PLIST_BOOLEAN,
-        PLIST_UINT,
-        PLIST_REAL,
-        PLIST_STRING,
-        PLIST_UNICODE,
-        PLIST_ARRAY,
-        PLIST_DICT,
-        PLIST_DATE,
-        PLIST_DATA,
-        PLIST_KEY,
-        PLIST_NONE
+        PLIST_BOOLEAN,  /**< Boolean, scalar type */
+        PLIST_UINT,     /**< Unsigned integer, scalar type */
+        PLIST_REAL,     /**< Real, scalar type */
+        PLIST_STRING,   /**< ASCII string, scalar type */
+        PLIST_UNICODE,  /**< Unicode strin, scalar type */
+        PLIST_ARRAY,    /**< Ordered array, structured type */
+        PLIST_DICT,     /**< Unordered dictionary (key/value pair), structured type */
+        PLIST_DATE,     /**< Date, scalar type */
+        PLIST_DATA,     /**< Binary data, scalar type */
+        PLIST_KEY,      /**< Key in dictionaries (ASCII String), scalar type */
+        PLIST_NONE      /**< No type */
 } plist_type;
 
-//Plist creation and edition
-//utilitary functions to create root nodes (supposed to be dict or array)
+
+/********************************************
+ *                                          *
+ *          Creation & Destruction          *
+ *                                          *
+ ********************************************/
+
+/**
+ * Create a new root plist_t type #PLIST_DICT
+ *
+ * @return the created plist
+ * @sa #plist_type
+ */
 plist_t plist_new_dict();
+
+/**
+ * Create a new root plist_t type #PLIST_ARRAY
+ *
+ * @return the created plist
+ * @sa #plist_type
+ */
 plist_t plist_new_array();
 
+/**
+ * Destruct a plist_t node and all its children recursively
+ *
+ * @param plist the plist to free
+ */
+void plist_free(plist_t plist);
 
-//Plist edition, only work for dict and array node
+/********************************************
+ *                                          *
+ *            Tree navigation               *
+ *                                          *
+ ********************************************/
+
+/**
+ * Get the first child of a node
+ *
+ * @param node the first child
+ */
+plist_t plist_get_first_child(plist_t node);
+
+
+/**
+ * Get the next sibling of a node
+ *
+ * @param node the next sibling
+ */
+plist_t plist_get_next_sibling(plist_t node);
+
+
+/**
+ * Get the previous sibling of a node
+ *
+ * @param node the previous sibling
+ */
+plist_t plist_get_prev_sibling(plist_t node);
+
+/********************************************
+ *                                          *
+ *                Setters                   *
+ *                                          *
+ ********************************************/
+
+/**
+ * Add a subnode to a node. The node must be of a structured type
+ * (ie #PLIST_DICT or #PLIST_ARRAY). This function fails silently
+ * if subnode already has a father.
+ *
+ * @param node the node to add a children to
+ * @param subnode the children node
+ */
 void plist_add_sub_node(plist_t node, plist_t subnode);
 
+/**
+ * Add a subnode of type #PLIST_KEY to a node. The node must be of a structured type
+ * (ie #PLIST_DICT or #PLIST_ARRAY).
+ *
+ * @param node the node to add a children to
+ * @param val the key value encoded as an ASCII string (must be null terminated)
+ */
 void plist_add_sub_key_el(plist_t node, const char* val);
+
+/**
+ * Add a subnode of type #PLIST_STRING to a node. The node must be of a structured type
+ * (ie #PLIST_DICT or #PLIST_ARRAY).
+ *
+ * @param node the node to add a children to
+ * @param val the string value encoded as an ASCII string (must be null terminated)
+ */
 void plist_add_sub_string_el(plist_t node, const char* val);
+
+/**
+ * Add a subnode of type #PLIST_BOOLEAN to a node. The node must be of a structured type
+ * (ie #PLIST_DICT or #PLIST_ARRAY).
+ *
+ * @param node the node to add a children to
+ * @param val the boolean value (TRUE or FALSE)
+ */
 void plist_add_sub_bool_el(plist_t node, uint8_t val);
+
+/**
+ * Add a subnode of type #PLIST_UINT to a node. The node must be of a structured type
+ * (ie #PLIST_DICT or #PLIST_ARRAY).
+ *
+ * @param node the node to add a children to
+ * @param val the unsigned integer value
+ */
 void plist_add_sub_uint_el(plist_t node, uint64_t val);
+
+/**
+ * Add a subnode of type #PLIST_REAL to a node. The node must be of a structured type
+ * (ie #PLIST_DICT or #PLIST_ARRAY).
+ *
+ * @param node the node to add a children to
+ * @param val the real value
+ */
 void plist_add_sub_real_el(plist_t node, double val);
+
+/**
+ * Add a subnode of type #PLIST_DATA to a node. The node must be of a structured type
+ * (ie #PLIST_DICT or #PLIST_ARRAY).
+ *
+ * @param node the node to add a children to
+ * @param val the binary buffer
+ * @param length the length of the buffer
+ */
 void plist_add_sub_data_el(plist_t node, const char* val, uint64_t length);
+
+/**
+ * Add a subnode of type #PLIST_UNICODE to a node. The node must be of a structured type
+ * (ie #PLIST_DICT or #PLIST_ARRAY).
+ *
+ * @param node the node to add a children to
+ * @param val the unicode string encoded in UTF-8 (must be null terminated)
+ */
 void plist_add_sub_unicode_el(plist_t node, const char* val);
-void plist_add_sub_date_el(plist_t node, int32_t sec, int32_t usec);
 
-//plist free
-void plist_free(plist_t plist);
+/**
+ * Add a subnode of type #PLIST_DATE to a node. The node must be of a structured type
+ * (ie #PLIST_DICT or #PLIST_ARRAY).
+ *
+ * @param node the node to add a children to
+ * @param sec the number of seconds since 01/01/2001
+ * @param usec the number of microseconds
+ */
+void plist_add_sub_date_el(plist_t node, int32_t sec, int32_t usec);
 
-//plist navigation
-plist_t plist_get_first_child(plist_t node);
-plist_t plist_get_next_sibling(plist_t node);
-plist_t plist_get_prev_sibling(plist_t node);
 
-//utili function to find first (and only the first encountred) corresponding node
-plist_t plist_find_node_by_key(plist_t plist, const char *value);
-plist_t plist_find_node_by_string(plist_t plist, const char *value);
+/********************************************
+ *                                          *
+ *                Getters                   *
+ *                                          *
+ ********************************************/
 
-//Plist reading
+/**
+ * Get the #plist_type of a node.
+ *
+ * @param node the node
+ * @return the type of the node
+ */
 plist_type plist_get_node_type(plist_t node);
 
+/**
+ * Get the value of a #PLIST_KEY node.
+ * This function does nothing if node is not of type #PLIST_KEY
+ *
+ * @param node the node
+ * @param val a pointer to a C-string. This function allocates the memory,
+ *            caller is responsible for freeing it.
+ */
 void plist_get_key_val(plist_t node, char** val);
+
+/**
+ * Get the value of a #PLIST_STRING node.
+ * This function does nothing if node is not of type #PLIST_STRING
+ *
+ * @param node the node
+ * @param val a pointer to a C-string. This function allocates the memory,
+ *            caller is responsible for freeing it.
+ */
 void plist_get_string_val(plist_t node, char** val);
+
+/**
+ * Get the value of a #PLIST_BOOLEAN node.
+ * This function does nothing if node is not of type #PLIST_BOOLEAN
+ *
+ * @param node the node
+ * @param val a pointer to a uint8_t variable.
+ */
 void plist_get_bool_val(plist_t node, uint8_t* val);
+
+/**
+ * Get the value of a #PLIST_UINT node.
+ * This function does nothing if node is not of type #PLIST_UINT
+ *
+ * @param node the node
+ * @param val a pointer to a uint64_t variable.
+ */
 void plist_get_uint_val(plist_t node, uint64_t* val);
+
+/**
+ * Get the value of a #PLIST_REAL node.
+ * This function does nothing if node is not of type #PLIST_REAL
+ *
+ * @param node the node
+ * @param val a pointer to a double variable.
+ */
 void plist_get_real_val(plist_t node, double* val);
+
+/**
+ * Get the value of a #PLIST_DATA node.
+ * This function does nothing if node is not of type #PLIST_DATA
+ *
+ * @param node the node
+ * @param val a pointer to an unallocated char buffer. This function allocates the memory,
+ *            caller is responsible for freeing it.
+ */
 void plist_get_data_val(plist_t node, char** val, uint64_t* length);
+
+/**
+ * Get the value of a #PLIST_UNICODE node.
+ * This function does nothing if node is not of type #PLIST_UNICODE
+ *
+ * @param node the node
+ * @param val a pointer to a C-string. This function allocates the memory,
+ *            caller is responsible for freeing it. Data is UTF-8 encoded.
+ */
 void plist_get_unicode_val(plist_t node, char** val);
+
+/**
+ * Get the value of a #PLIST_DATE node.
+ * This function does nothing if node is not of type #PLIST_DATE
+ *
+ * @param node the node
+ * @param sec a pointer to an int32_t variable. Represents the number of seconds since 01/01/2001.
+ * @param usec a pointer to an int32_t variable. Represents the number of microseconds
+ */
 void plist_get_date_val(plist_t node, int32_t* sec, int32_t* usec);
 
 
-//import and export functions
+
+/********************************************
+ *                                          *
+ *            Import & Export               *
+ *                                          *
+ ********************************************/
+
+/**
+ * Export the #plist_t structure to XML format.
+ *
+ * @param plist the root node to export
+ * @param plist_xml a pointer to a C-string. This function allocates the memory,
+ *            caller is responsible for freeing it. Data is UTF-8 encoded.
+ * @param length a pointer to an uint32_t variable. Represents the length of the allocated buffer.
+ */
 void plist_to_xml(plist_t plist, char **plist_xml, uint32_t * length);
+
+/**
+ * Export the #plist_t structure to binary format.
+ *
+ * @param plist the root node to export
+ * @param plist_bin a pointer to a char* buffer. This function allocates the memory,
+ *            caller is responsible for freeing it.
+ * @param length a pointer to an uint32_t variable. Represents the length of the allocated buffer.
+ */
 void plist_to_bin(plist_t plist, char **plist_bin, uint32_t * length);
 
+/**
+ * Import the #plist_t structure from XML format.
+ *
+ * @param plist_xml a pointer to the xml buffer.
+ * @param length length of the buffer to read.
+ * @param plist a pointer to the imported plist.
+ */
 void plist_from_xml(const char *plist_xml, uint32_t length, plist_t * plist);
+
+/**
+ * Import the #plist_t structure from binary format.
+ *
+ * @param plist_bin a pointer to the xml buffer.
+ * @param length length of the buffer to read.
+ * @param plist a pointer to the imported plist.
+ */
 void plist_from_bin(const char *plist_bin, uint32_t length, plist_t * plist);
 
+
+
+/********************************************
+ *                                          *
+ *                 Utils                    *
+ *                                          *
+ ********************************************/
+
+/**
+ * Find the first encountered #PLIST_KEY node mathing that key.
+ * Search is breath first order.
+ *
+ * @param plist the root node of the plist structure.
+ * @param value the ASCII Key to match.
+ */
+plist_t plist_find_node_by_key(plist_t plist, const char *value);
+
+/**
+ * Find the first encountered #PLIST_STRING node mathing that string.
+ * Search is breath first order.
+ *
+ * @param plist the root node of the plist structure.
+ * @param value the ASCII String to match.
+ */
+plist_t plist_find_node_by_string(plist_t plist, const char *value);
+
+
+/*@}*/
+
+
 #ifdef __cplusplus
 }
 #endif