diff --git a/shared/strbuf.h b/shared/strbuf.h
index 8824afd..64a5ba0 100644
--- a/shared/strbuf.h
+++ b/shared/strbuf.h
@@ -27,5 +27,29 @@ const char *strbuf_str(struct strbuf *buf);
 
 bool strbuf_pushchar(struct strbuf *buf, char ch);
 size_t strbuf_pushchars(struct strbuf *buf, const char *str);
+
+/*
+ * Remove the last char from buf.
+ *
+ * No reallocation is done, so it's guaranteed @buf will have at least 1 char available to
+ * be filled after this call, as long as @buf wasn't empty.
+ */
 void strbuf_popchar(struct strbuf *buf);
+
+/*
+ * Remove the last @n chars from buf.
+ *
+ * No reallocation is done, so it's guaranteed @buf will have at least @n chars available
+ * to be filled after this call, as long as @buf had @n chars allocated before.
+ *
+ * Example:
+ *
+ * 	struct strbuf buf;
+ * 	strbuf_init(&buf);
+ * 	strbuf_pushchars(&buf, "foobar");
+ * 	strbuf_popchars(&buf, 5);
+ *
+ * After these calls @buf is [ 'f', x, x, x, ... ], where "x" means undefined. However it's
+ * guaranteed to have (at least) 5 chars available without needing to reallocate.
+ */
 void strbuf_popchars(struct strbuf *buf, size_t n);
diff --git a/testsuite/test-strbuf.c b/testsuite/test-strbuf.c
index cc093ec..e4bfd05 100644
--- a/testsuite/test-strbuf.c
+++ b/testsuite/test-strbuf.c
@@ -62,6 +62,11 @@ static int test_strbuf_pushchars(const struct test *t)
 		lastwordlen = strlen(c);
 	}
 
+	/*
+	 * Replace the last space char, which also guarantees there's at least 1 char
+	 * available for the '\0' added by strbuf_str() so result1 == buf.bytes should be
+	 * true
+	 */
 	strbuf_popchar(&buf);
 	result1 = strbuf_str(&buf);
 	assert_return(result1 == buf.bytes, EXIT_FAILURE);