Update docstrings and minor refactor

components/core/src/clp_s/ArchiveReader.hpp

@@ -180,6 +180,10 @@ class ArchiveReader {
      * a row for the same table_id a cached buffer is returned. This function allows the caller to
      * ask for the same buffer to be reused to read multiple different tables: this can save memory
      * allocations, but can only be used when tables are read one at a time.
+     * @param table_id
+     * @param reuse_buffer when true the same buffer is reused across invocations, overwriting data
+     * returned previous calls to read_table
+     * @return a buffer containing the decompressed table identified by table_id
      */
     std::shared_ptr<char[]> read_table(size_t table_id, bool reuse_buffer);
 

components/core/src/clp_s/TableReader.cpp

@@ -64,7 +64,7 @@ void TableReader::close() {
             throw OperationFailed(ErrorCodeNotReady, __FILE__, __LINE__);
     }
     m_tables_reader.close();
-    m_previous_table_id = 0;
+    m_prev_table_id = 0;
     m_table_metadata.clear();
     m_state = TableReaderState::Uninitialized;
 }
@@ -80,14 +80,14 @@ void TableReader::read_table(size_t table_id, std::shared_ptr<char[]>& buf, size
             m_state = TableReaderState::ReadingTables;
             break;
         case TableReaderState::ReadingTables:
-            if (m_previous_table_id >= table_id) {
+            if (m_prev_table_id >= table_id) {
                 throw OperationFailed(ErrorCodeBadParam, __FILE__, __LINE__);
             }
             break;
         default:
             throw OperationFailed(ErrorCodeNotReady, __FILE__, __LINE__);
     }
-    m_previous_table_id = table_id;
+    m_prev_table_id = table_id;
 
     auto& [file_offset, uncompressed_size] = m_table_metadata[table_id];
     m_tables_reader.try_seek_from_begin(file_offset);

components/core/src/clp_s/TableReader.hpp

@@ -35,11 +35,13 @@ class TableReader {
     /**
      * Reads table metadata from the provided compression stream. Must be invoked before reading
      * tables.
+     * @param decompressor an open ZstdDecompressor pointing to the table metadata
      */
     void read_metadata(ZstdDecompressor& decompressor);
 
     /**
      * Opens a file reader for the tables section. Must be invoked before reading tables.
+     * @param tables_file_path the path to the tables file for the archive being read
      */
     void open_tables(std::string const& tables_file_path);
 
@@ -60,9 +62,10 @@ class TableReader {
      * being decompressed.
      *
      * @param table_id
-     * @param buf
-     * @param buf_size
-     * @return a shared_ptr to a buffer containing the requested table
+     * @param buf a shared ptr to the buffer where the table will be read. The buffer gets resized
+     * if it is too small to contain the requested table.
+     * @param buf_size the size of the underlying buffer owned by buf -- passed and updated by
+     * reference
      */
     void read_table(size_t table_id, std::shared_ptr<char[]>& buf, size_t& buf_size);
 
@@ -83,7 +86,7 @@ class TableReader {
     FileReader m_tables_reader;
     ZstdDecompressor m_tables_decompressor;
     TableReaderState m_state{TableReaderState::Uninitialized};
-    size_t m_previous_table_id{0ULL};
+    size_t m_prev_table_id{0ULL};
 };
 
 }  // namespace clp_s