treewide: add buf_finish() and replace manual free(buf.buf) calls

include/common/buf.h

@@ -34,7 +34,7 @@ void buf_expand_shell_variables(struct buf *s);
 /**
  * buf_init - allocate NULL-terminated C string buffer
  * @s: buffer
- * Note: use free(s->buf) to free it
+ * Note: use buf_finish(buf) to free it
  */
 void buf_init(struct buf *s);
 
@@ -55,13 +55,41 @@ void buf_add_char(struct buf *s, char data);
 /**
  * buf_clear - clear the buffer, internal allocations are preserved
  * @s: buffer
+ *
+ * This is the appropriate function to call to re-use the buffer
+ * in a loop or similar situations as it simply reuses the already
+ * existing heap allocations.
  */
 void buf_clear(struct buf *s);
 
 /**
  * buf_reset - reset the buffer, internal allocations are free'd
  * @s: buffer
+ *
+ * The buffer will automatically be re-initialized so can be used again.
+ *
+ * This function should not be used in loops as it will free and then
+ * re-allocate heap memory. However, if the buffer becomes too big
+ * and the internal allocation should be free'd this is the correct
+ * function to use.
  */
 void buf_reset(struct buf *s);
 
+/**
+ * buf_finish - free all internal allocations
+ * @s: buffer
+ *
+ * The state of the buffer after this call is undefined.
+ * It can be re-initalized via buf_init() however.
+ *
+ * Use this for the usual case of a stack allocated buf instance:
+ *   struct buf buf;
+ *   buf_init(&buf);
+ *   buf_add(&buf, "some");
+ *   buf_add(&buf, "thing");
+ *   do_something_with(buf.buf);
+ *   buf_finish(&buf);
+ */
+void buf_finish(struct buf *s);
+
 #endif /* LABWC_BUF_H */