tal: document tal_steal(ctx, NULL) as OK.

[ccan] / ccan / tal / tal.h

diff --git a/ccan/tal/tal.h b/ccan/tal/tal.h
index e25dcb92985922acc5a50007f5c397ddb4aa9237..20cd89c5ee956ef0bc2e9dc63d27810b5ca0bf0d 100644 (file)
--- a/ccan/tal/tal.h
+++ b/ccan/tal/tal.h
@@ -131,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'. */
@@ -164,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)))
@@ -195,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)))