strbuf: Document strbuf_popchar(s)

Document the behavior for these functions and also clarify why the
testsuite can check the buffer for equality after calling strbuf_str().

Signed-off-by: Lucas De Marchi <lucas.de.marchi@gmail.com>
Reviewed-by: Emil Velikov <emil.l.velikov@gmail.com>
Link: https://github.com/kmod-project/kmod/pull/239

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);

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);