/**
* @brief Free a chunk of talloc memory.
*
- * This function frees a piece of talloc memory, and all its children. It
- * operates recursively on its children. You can call talloc_free() on any
- * pointer returned by talloc().
+ * The talloc_free() function frees a piece of talloc memory, and all its
+ * children. You can call talloc_free() on any pointer returned by
+ * talloc().
*
- * If this pointer has an additional parent when talloc_free() is called then
- * the memory is not actually released, but instead the most recently
- * established parent is destroyed. See talloc_reference() for details on
- * establishing additional parents.
+ * The return value of talloc_free() indicates success or failure, with 0
+ * returned for success and -1 for failure. A possible failure condition
+ * is if the pointer had a destructor attached to it and the destructor
+ * returned -1. See talloc_set_destructor() for details on
+ * destructors. Likewise, if "ptr" is NULL, then the function will make
+ * no modifications and return -1.
*
- * For more control on which parent is removed, see talloc_unlink().
+ * If this pointer has an additional parent when talloc_free() is called
+ * then the memory is not actually released, but instead the most
+ * recently established parent is destroyed. See talloc_reference() for
+ * details on establishing additional parents.
+ *
+ * For more control on which parent is removed, see talloc_unlink()
+ *
+ * talloc_free() operates recursively on its children.
*
* From the 2.0 version of talloc, as a special case, talloc_free() is
* refused on pointers that have more than one parent, as talloc would
*
* @param[in] ptr The chunk to be freed.
*
- * @return Returns 0 on success and -1 on error. The only possible
+ * @return Returns 0 on success and -1 on error. A possible
* failure condition is if the pointer had a destructor
- * attached to it and the destructor returned -1.
+ * attached to it and the destructor returned -1. Likewise,
+ * if "ptr" is NULL, then the function will make no
+ * modifications and returns -1.
*
* Example:
* @code
talloc().
The return value of talloc_free() indicates success or failure, with 0
-returned for success and -1 for failure. The only possible failure
-condition is if the pointer had a destructor attached to it and the
-destructor returned -1. See talloc_set_destructor() for details on
-destructors.
+returned for success and -1 for failure. A possible failure condition
+is if the pointer had a destructor attached to it and the destructor
+returned -1. See talloc_set_destructor() for details on
+destructors. Likewise, if "ptr" is NULL, then the function will make
+no modifications and returns -1.
If this pointer has an additional parent when talloc_free() is called
then the memory is not actually released, but instead the most