diff --git a/include/common/buffer.h b/include/common/buffer.h
index 7ac98bf..1a577ca 100644
--- a/include/common/buffer.h
+++ b/include/common/buffer.h
@@ -769,6 +769,13 @@
 }
 
 
+/* 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)
diff --git a/src/buffer.c b/src/buffer.c
index 167b75a..79cc133 100644
--- a/src/buffer.c
+++ b/src/buffer.c
@@ -247,6 +247,7 @@
 	fflush(o);
 }
 
+/* see offer_buffer() for details */
 void __offer_buffer(void *from, unsigned int threshold)
 {
 	struct buffer_wait *wait, *bak;