DOC: buffers: clarify the purpose of the <from> pointer in offer_buffers()

This one is only used to compare pointers and NULL is permitted though
this is far from being clear.

include/common/buffer.h

@@ -769,6 +769,13 @@ static inline struct buffer *b_alloc_margin(struct buffer **buf, int margin)
 }
 
 
+/* Offer a buffer currently belonging to target <from> to whoever needs one.
+ * Any pointer is valid for <from>, including NULL. Its purpose is to avoid
+ * passing a buffer to oneself in case of failed allocations (e.g. need two
+ * buffers, get one, fail, release it and wake up self again). In case of
+ * normal buffer release where it is expected that the caller is not waiting
+ * for a buffer, NULL is fine.
+ */
 void __offer_buffer(void *from, unsigned int threshold);
 
 static inline void offer_buffers(void *from, unsigned int threshold)

src/buffer.c

@@ -247,6 +247,7 @@ void buffer_dump(FILE *o, struct buffer *b, int from, int to)
 	fflush(o);
 }
 
+/* see offer_buffer() for details */
 void __offer_buffer(void *from, unsigned int threshold)
 {
 	struct buffer_wait *wait, *bak;