MEDIUM: buffers: add some new primitives and rework existing ones

A number of primitives were missing for buffer management, and some
of them were particularly awkward to use. Specifically, the functions
used to compute free space could not always be used depending what was
wrapping in the buffers. Some documentation has been added about how
the buffers work and their properties. Some functions are still missing
such as a buffer replacement which would support wrapping buffers.
diff --git a/src/buffers.c b/src/buffers.c
index 44b3f7d..43c0647 100644
--- a/src/buffers.c
+++ b/src/buffers.c
@@ -196,7 +196,7 @@
 		return 0;
 
 	/* OK so the data fits in the buffer in one or two blocks */
-	max = buffer_contig_space_with_len(buf, max);
+	max = buffer_contig_space_with_res(buf, buf->size - max);
 	memcpy(buf->r, blk, MIN(len, max));
 	if (len > max)
 		memcpy(buf->data, blk + max, len - max);