buffer: add some comments to clarify allocation strategy

Closes #116

2 files changed, 9 insertions, 4 deletions

diff --git a/buffer.c b/buffer.c
index 6a16a7b..1577e6f 100644
--- a/buffer.c
+++ b/buffer.c
@@ -11,9 +11,12 @@ void buffer_init(Buffer *buf) {
 }
 
 bool buffer_grow(Buffer *buf, size_t size) {
+	/* ensure minimal buffer size, to avoid repeated realloc(3) calls */
 	if (size < BUF_SIZE)
 		size = BUF_SIZE;
 	if (buf->size < size) {
+		/* if this is not the first allocation i.e. the buffer is
+		 * currently full, double the size to avoid memory pressure */
 		if (buf->size > 0)
 			size *= 2;
 		char *data = realloc(buf->data, size);
diff --git a/buffer.h b/buffer.h
index 4c5ae33..0dc2dc6 100644
--- a/buffer.h
+++ b/buffer.h
@@ -5,15 +5,16 @@
 #include <stdbool.h>
 #include "text.h"
 
-typedef struct {       /* a dynamically growing buffer storing arbitrary data */
+/* a dynamically growing buffer storing arbitrary data, used for registers/macros */
+typedef struct {
 	char *data;    /* NULL if empty */
 	size_t len;    /* current length of data */
 	size_t size;   /* maximal capacity of the buffer */
 } Buffer;
 
-/* initalize a (stack allocated) Buffer insteance */
+/* initalize a (stack allocated) Buffer instance */
 void buffer_init(Buffer*);
-/* relase/free all data stored in this buffer, reset size to zero */
+/* release/free all data stored in this buffer, reset size to zero */
 void buffer_release(Buffer*);
 /* reserve space to store at least size bytes in this buffer.*/
 bool buffer_grow(Buffer*, size_t size);
@@ -31,8 +32,9 @@ bool buffer_insert0(Buffer*, size_t pos, const char *data);
 bool buffer_append(Buffer*, const void *data, size_t len);
 /* append NUl-terminated data */
 bool buffer_append0(Buffer*, const char *data);
-
+/* insert new data at the start of the buffer */
 bool buffer_prepend(Buffer*, const void *data, size_t len);
+/* prepend NUL-terminated data */
 bool buffer_prepend0(Buffer*, const char *data);
 
 #endif