tal: tal_dump() now prints to stderr.

[ccan] / ccan / tal / tal.h

diff --git a/ccan/tal/tal.h b/ccan/tal/tal.h
index 865a696713c88d9243f64515200b49c7c164e554..a3a1549153fe4f42636b116d33162c774982df46 100644 (file)
--- a/ccan/tal/tal.h
+++ b/ccan/tal/tal.h
@@ -106,6 +106,9 @@ void *tal_free(const tal_t *p);
  * This returns true on success (and may move *@p), or false on failure.
  * On success, tal_count() of *@p will be @count.
  *
+ * Note: if *p is take(), it will still be take() upon return, even if it
+ * has been moved.
+ *
  * Example:
  *     tal_resize(&p, 100);
  */
@@ -128,10 +131,11 @@ void *tal_free(const tal_t *p);
 /**
  * tal_steal - change the parent of a tal-allocated pointer.
  * @ctx: The new parent.
- * @ptr: The tal allocated object to move.
+ * @ptr: The tal allocated object to move, or NULL.
  *
  * This may need to perform an allocation, in which case it may fail; thus
- * it can return NULL, otherwise returns @ptr.
+ * it can return NULL, otherwise returns @ptr.  If @ptr is NULL, this function does
+ * nothing.
  */
 #if HAVE_STATEMENT_EXPR
 /* Weird macro avoids gcc's 'warning: value computed is not used'. */
@@ -161,7 +165,8 @@ void *tal_free(const tal_t *p);
  * @function: the function to call before it's freed.
  *
  * If @function has not been successfully added as a destructor, this returns
- * false.
+ * false.  Note that if we're inside the destructor call itself, this will
+ * return false.
  */
 #define tal_del_destructor(ptr, function)                                    \
        tal_del_destructor_((ptr), typesafe_cb(void, void *, (function), (ptr)))
@@ -192,7 +197,8 @@ void *tal_free(const tal_t *p);
  * @function: the function to call before it's freed.
  *
  * If @function has not been successfully added as a destructor, this returns
- * false.
+ * false.  Note that if we're inside the destructor call itself, this will
+ * return false.
  */
 #define tal_del_destructor(ptr, function)                                    \
        tal_del_destructor_((ptr), typesafe_cb(void, void *, (function), (ptr)))
@@ -450,7 +456,7 @@ bool tal_check(const tal_t *ctx, const char *errorstr);
 
 #ifdef CCAN_TAL_DEBUG
 /**
- * tal_dump - dump entire tal tree.
+ * tal_dump - dump entire tal tree to stderr.
  *
  * This is a helper for debugging tal itself, which dumps all the tal internal
  * state.