added some docs

README.md

@@ -124,13 +124,19 @@ GapBuffer *GapBuffer_create(size_t capacity);
 GapBuffer *GapBuffer_createUsingMemory(void *mem, size_t len, void (*free)(void*));
 ```
 
-The basic option is using `GapBuffer_create`, which instanciates a buffer with a given initial capacity allocating space through the libc allocator.  `GapBuffer_createUsingMemory` doesn't use dynamic memory and does its job using only memory provided by the caller. Either way, if it wasn't possible to instanciate the gap buffer (either because the dynamic allocation failed or the provided memory isn't big enough), NULL is returned.
+The basic option is using `GapBuffer_create`, which instanciates a buffer with a given initial capacity allocating space through the libc allocator. `GapBuffer_createUsingMemory` doesn't use dynamic memory and does its job using only memory provided by the caller. Either way, if it wasn't possible to instanciate the gap buffer (either because the dynamic allocation failed or the provided memory isn't big enough), NULL is returned.
 Once you're done with the buffer, you'll need to deallocate it using
 
 ```c
 void GapBuffer_destroy(GapBuffer *buff);
 ```
 
+It's also possible to clone a gap buffer object using
+```c
+GapBuffer *GapBuffer_cloneUsingMemory(void *mem, size_t len, void (*free)(void*), const GapBuffer *src);
+```
+which behaves like `GapBuffer_createUsingMemory` but copies the contents of a pre-existing gap buffer into the newly created one. This can be used to resize a gap buffer object by moving it.
+
 ### Text insertion
 To insert text, you must use the function
 ```c
@@ -142,9 +148,9 @@ The validity of the string is checked before insertion to make sure the buffer o
 
 An alternative function is
 ```c
-bool       GapBuffer_insertStringMaybeRelocate(GapBuffer **buff, const char *str, size_t len);
+bool GapBuffer_insertStringMaybeRelocate(GapBuffer **buff, const char *str, size_t len);
 ```
-which behaves like the previous one but relocates the buffer if no more space is available in the old one. If relocation fails, false is returned.
+which behaves like the previous one but relocates the buffer if no more space is available in the old one. If relocation fails, false is returned. If this function succedes, the pointer to the buffer object is changed. 
 
 ### Cursor position
 To move the cursor position you can use the functions
@@ -160,6 +166,4 @@ To delete text, you need to do so relative to the cursor's position. You can eit
 void GapBuffer_removeForwards(GapBuffer *buff, size_t num);
 void GapBuffer_removeBackwards(GapBuffer *buff, size_t num);
 ```
-Where `num` is the number of unicode characters to be removed. If less than `num` characters are available, then they are all removed.
+Where `num` is the number of unicode characters to be removed. If less than `num` characters are available, then they are all removed.
-
-## Testing

gap_buffer.c

@@ -29,6 +29,21 @@ PRIVATE size_t getByteCount(GapBuffer *buff)
     return buff->total - buff->gap_length;
 }
 
+/* Symbol: GapBuffer_createUsingMemory
+**
+**   Initialize a gap buffer object using the provided
+**   memory region.
+**
+** Arguments:
+**   - mem: Address of the memory region
+**
+**   - len: Length (in bytes) of the memory region
+**          referred by [mem]
+**
+**   - free: Function to be called on the [mem] pointer
+**           when the gap buffer object is destroyed.
+**
+*/
 GapBuffer *GapBuffer_createUsingMemory(void *mem, size_t len, void (*free)(void*))
 {
     if (mem == NULL || len < sizeof(GapBuffer)) {
@@ -112,6 +127,27 @@ PRIVATE bool insertBytesAfterCursor(GapBuffer *buff, String str)
     return true;
 }
 
+/* Symbol: GapBuffer_cloneUsingMemory
+**
+**   Clone a gap buffer object into the provided memory 
+**   region. The provided memory region size can be of
+**   a different size than the source object's. 
+**
+** Arguments:
+**   - mem: Address of the memory region.
+**
+**   - len: Length (in bytes) of the memory region
+**          referred by [mem].
+**
+**   - free: Function to be called on the [mem] pointer
+**           when the gap buffer object is destroyed.
+**
+**   - src: Gap buffer object to be cloned.
+**
+** Notes:
+**   - This makes it possible to grow a gap buffer object
+**     that has no free space left.
+*/
 GapBuffer *GapBuffer_cloneUsingMemory(void *mem, size_t len, 
                                       void (*free)(void*),
                                       const GapBuffer *src)
@@ -252,6 +288,24 @@ PRIVATE bool isValidUTF8(const char *str, size_t len)
     return true;
 }
 
+/* Symbol: GapBuffer_insertString
+**
+**   Insert a UTF8-encoded string into a gap buffer object.
+**
+** Arguments:
+**   - buff: Gap buffer object where the string will be
+**           inserted.
+**
+**   - str: Address to the UTF8-encoded string (doesn't need
+**          to be zero-terminated).
+**
+**   - len: Length of the sequence [str]
+**
+** Returns:
+**   [false] if there wasn't enough space in the buffer 
+**   or the provided string isn't valid UTF8. Returns
+**   [true] if all went well.
+*/
 bool GapBuffer_insertString(GapBuffer *buff, const char *str, size_t len)
 {
     if (!isValidUTF8(str, len))