update documentation for GapBuffer

src/core/GapBuffer.cc

@@ -23,22 +23,6 @@ GapBuffer::~GapBuffer()
     System::free_pages(m_buffer, m_buffer_size >> System::page_size_log);
 }
 
-void GapBuffer::compact()
-{
-    if (m_gap_position < m_size)
-    {
-        memmove(&m_buffer[m_gap_position], &m_buffer[m_gap_position + gap_size()], m_size - m_gap_position);
-        m_gap_position = m_size;
-    }
-}
-
-/**
- * Insert code_point into the gap buffer at position position.
- *
- * @param position Position in the gap buffer to insert the code point at.
- * @param data Pointer to the data to insert.
- * @param length Length of the data to insert.
- */
 void GapBuffer::insert(size_t position, const uint8_t * data, size_t length)
 {
     ensure_free(length);
@@ -48,22 +32,12 @@ void GapBuffer::insert(size_t position, const uint8_t * data, size_t length)
     m_size += length;
 }
 
-/**
- * Get the contents of the gap buffer as a string.
- *
- * This makes a copy of the entire buffer in a std::string. This method is
- * intended for use by unit tests.
- */
 std::string GapBuffer::get_string()
 {
     compact();
     return std::string((char *)m_buffer, m_size);
 }
 
-/**
- * Verify that there is enough free space in the gap, and if not, grow the gap
- * and move data.
- */
 void GapBuffer::ensure_free(size_t length)
 {
     if (gap_size() < length)
@@ -84,11 +58,6 @@ void GapBuffer::ensure_free(size_t length)
     }
 }
 
-/**
- * Move the gap buffer gap position to the requested position.
- *
- * @param position New gap position. Must be <= m_size.
- */
 void GapBuffer::move_gap(size_t position)
 {
     if (position != m_gap_position)

src/core/GapBuffer.h

@@ -8,11 +8,66 @@
 class GapBuffer
 {
 public:
+    /**
+     * Create a new GapBuffer object.
+     *
+     * The GapBuffer will allocate its own memory.
+     */
     GapBuffer();
+
+    /**
+     * Create a GapBuffer object that points to preallocated memory.
+     *
+     * The GapBuffer object will take over ownership of the allocated memory.
+     *
+     * @param buffer
+     *   Pointer to buffer allocated by System::alloc_pages().
+     * @param buffer_size
+     *   Size of the buffer allocated by System::alloc_pages().
+     * @param size
+     *   Size of the data in the buffer.
+     */
     GapBuffer(uint8_t * buffer, size_t buffer_size, size_t size);
+
+    /**
+     * Destroy the GapBuffer object and free its memory.
+     */
     ~GapBuffer();
-    size_t buffer_size() const { return m_buffer_size; }
-    size_t size() const { return m_size; }
+
+    /**
+     * Insert data into the gap buffer at the given position.
+     *
+     * @param position
+     *   Position in the gap buffer to insert the code point at.
+     * @param data
+     *   Pointer to the data to insert.
+     * @param length
+     *   Length of the data to insert.
+     */
+    void insert(size_t position, const uint8_t * data, size_t length);
+
+    /**
+     * Get the contents of the gap buffer as a string.
+     *
+     * This makes a copy of the entire buffer in a std::string. This method is
+     * intended for use by unit tests.
+     */
+    std::string get_string();
+
+    /**
+     * Get the size of the data stored within the buffer.
+     */
+    size_t size() const
+    {
+        return m_size;
+    }
+
+    /**
+     * Get the memory address of a buffer location.
+     *
+     * @param offset
+     *   The index into the gap buffer data.
+     */
     uint8_t * address(size_t offset) const
     {
         if (offset < m_gap_position)
@@ -24,18 +79,52 @@ public:
             return &m_buffer[offset + gap_size()];
         }
     }
-    size_t gap_size() const { return m_buffer_size - m_size; }
-    void compact();
-    void insert(size_t position, const uint8_t * data, size_t length);
-    std::string get_string();
+
+    /**
+     * Move buffer gap to the end of the buffer so the contents are congruent
+     * at the beginning of the buffer.
+     */
+    void compact()
+    {
+        move_gap(m_size);
+    }
 
 protected:
+    /** Address of the allocated memory buffer. */
     uint8_t * m_buffer;
+
+    /** Size of the allocated memory buffer. */
     size_t m_buffer_size;
+
+    /** Size of the data stored in the buffer. */
     size_t m_size;
+
+    /** Index of the gap in the memory buffer. */
     size_t m_gap_position;
 
+    /**
+     * Get the gap size.
+     */
+    size_t gap_size() const
+    {
+        return m_buffer_size - m_size;
+    }
+
+    /**
+     * Verify that there is enough free space in the gap, and if not, grow the
+     * gap and move data.
+     *
+     * @param length
+     *   The number of bytes that must be free.
+     */
     void ensure_free(size_t length);
+
+    /**
+     * Move the gap buffer gap position to the requested position.
+     *
+     * @param position
+     *   New gap position. Must be <= m_size.
+     */
     void move_gap(size_t position);
 };