summaryrefslogtreecommitdiffstats
path: root/include/plist/plist.h
diff options
context:
space:
mode:
authorGravatar Aaron Burghardt2014-04-22 10:05:56 -0400
committerGravatar Nikias Bassen2014-05-20 03:02:46 +0200
commit7b59a04d9406fde0847d1ce68c3bf2fde018c198 (patch)
treed0dc635c838c47ca674f372fc8dafc7d59ca6994 /include/plist/plist.h
parentb3cbcc256ab1f034dc3122517aab1be2a9d932e6 (diff)
downloadlibplist-7b59a04d9406fde0847d1ce68c3bf2fde018c198.tar.gz
libplist-7b59a04d9406fde0847d1ce68c3bf2fde018c198.tar.bz2
Added Doxygen comments to explicitly describe memory buffer ownership/responsibility.
Diffstat (limited to 'include/plist/plist.h')
-rw-r--r--include/plist/plist.h29
1 files changed, 17 insertions, 12 deletions
diff --git a/include/plist/plist.h b/include/plist/plist.h
index 4dd76a6..b855043 100644
--- a/include/plist/plist.h
+++ b/include/plist/plist.h
@@ -235,7 +235,7 @@ extern "C"
* The previous item at index n will be freed using #plist_free
*
* @param node the node of type #PLIST_ARRAY
- * @param item the new item at index n
+ * @param item the new item at index n. The array is responsible for freeing item when it is no longer needed.
* @param n the index of the item to get. Range is [0, array_size[. Assert if n is not in range.
*/
PLIST_API void plist_array_set_item(plist_t node, plist_t item, uint32_t n);
@@ -244,7 +244,7 @@ extern "C"
* Append a new item at the end of a #PLIST_ARRAY node.
*
* @param node the node of type #PLIST_ARRAY
- * @param item the new item
+ * @param item the new item. The array is responsible for freeing item when it is no longer needed.
*/
PLIST_API void plist_array_append_item(plist_t node, plist_t item);
@@ -252,14 +252,14 @@ extern "C"
* Insert a new item at position n in a #PLIST_ARRAY node.
*
* @param node the node of type #PLIST_ARRAY
- * @param item the new item to insert
+ * @param item the new item to insert. The array is responsible for freeing item when it is no longer needed.
* @param n The position at which the node will be stored. Range is [0, array_size[. Assert if n is not in range.
*/
PLIST_API void plist_array_insert_item(plist_t node, plist_t item, uint32_t n);
/**
* Remove an existing position in a #PLIST_ARRAY node.
- * Removed position will be freed using #plist_free
+ * Removed position will be freed using #plist_free.
*
* @param node the node of type #PLIST_ARRAY
* @param n The position to remove. Range is [0, array_size[. Assert if n is not in range.
@@ -281,8 +281,8 @@ extern "C"
PLIST_API uint32_t plist_dict_get_size(plist_t node);
/**
- * Create iterator of a #PLIST_DICT node.
- * The allocated iterator shoult be freed with tandard free function
+ * Create an iterator of a #PLIST_DICT node.
+ * The allocated iterator should be freed with the standard free function.
*
* @param node the node of type #PLIST_DICT
* @param iter iterator of the #PLIST_DICT node
@@ -294,8 +294,10 @@ extern "C"
*
* @param node the node of type #PLIST_DICT
* @param iter iterator of the dictionary
- * @param key a location to store the key, or NULL.
- * @param val a location to store the value, or NULL.
+ * @param key a location to store the key, or NULL. The caller is responsible
+ * for freeing the the returned string.
+ * @param val a location to store the value, or NULL. The caller should *not*
+ * free the returned value.
*/
PLIST_API void plist_dict_next_item(plist_t node, plist_dict_iter iter, char **key, plist_t *val);
@@ -303,7 +305,7 @@ extern "C"
* Get key associated to an item. Item must be member of a dictionary
*
* @param node the node
- * @param key a location to store the key.
+ * @param key a location to store the key. The caller is responsible for freeing the returned string.
*/
PLIST_API void plist_dict_get_item_key(plist_t node, char **key);
@@ -312,7 +314,8 @@ extern "C"
*
* @param node the node of type #PLIST_DICT
* @param key the identifier of the item to get.
- * @return the item or NULL if node is not of type #PLIST_DICT
+ * @return the item or NULL if node is not of type #PLIST_DICT. The caller should not free
+ * the returned node.
*/
PLIST_API plist_t plist_dict_get_item(plist_t node, const char* key);
@@ -485,7 +488,8 @@ extern "C"
* Forces type of node to #PLIST_STRING
*
* @param node the node
- * @param val the string value
+ * @param val the string value. The string is copied when set and will be
+ * freed by the node.
*/
PLIST_API void plist_set_string_val(plist_t node, const char *val);
@@ -521,7 +525,8 @@ extern "C"
* Forces type of node to #PLIST_DATA
*
* @param node the node
- * @param val the binary buffer
+ * @param val the binary buffer. The buffer is copied when set and will
+ * be freed by the node.
* @param length the length of the buffer
*/
PLIST_API void plist_set_data_val(plist_t node, const char *val, uint64_t length);