docs

include/arrow/table_info.hpp

@@ -8,19 +8,29 @@
 
 namespace tundradb {
 
+/// Precomputed per-column chunk boundaries for mapping logical row indices to
+/// Arrow chunks.
 class TableInfo {
  public:
+  /// Builds cumulative row boundaries for each column from the table’s chunked
+  /// arrays.
   explicit TableInfo(const std::shared_ptr<arrow::Table>& table);
 
+  /// Identifies which Arrow chunk holds a logical row and the offset inside
+  /// that chunk.
   struct ChunkInfo {
     int chunk_index;
     int64_t offset_in_chunk;
   };
+  /// Maps logical row_index in column column_index to a chunk and in-chunk
+  /// offset; throws if out of range.
   [[nodiscard]] ChunkInfo get_chunk_info(int column_index,
                                          int64_t row_index) const;
 
+  /// Number of columns (same as the source table).
   int num_columns() const { return chunk_boundaries_.size(); }
 
+  /// Total logical row count (same as table->num_rows() at construction).
   [[nodiscard]] int64_t num_rows() const { return num_rows_; }
 
  private:

include/common/config.hpp

@@ -13,6 +13,8 @@ constexpr size_t MANAGER_MEMORY_POOL_SIZE = 100 * 1024 * 1024;    // 100 MB
 constexpr size_t DATABASE_MEMORY_POOL_SIZE = 1024 * 1024 * 1024;  // 1 GB
 }  // namespace defaults
 
+/// Immutable database tuning: shard sizing, memory pools, storage path, and
+/// feature toggles.
 class DatabaseConfig {
  private:
   // Maximum number of nodes per shard
@@ -42,73 +44,96 @@ class DatabaseConfig {
   friend class DatabaseConfigBuilder;
 
  public:
+  /// Max nodes per shard before layout or split policy applies.
   size_t get_shard_capacity() const { return shard_capacity; }
+  /// Row chunk size used when creating tables.
   size_t get_chunk_size() const { return chunk_size; }
+  /// Per-shard memory pool budget in bytes.
   size_t get_shard_memory_pool_size() const { return shard_memory_pool_size; }
+  /// Shard-manager memory pool budget in bytes.
   size_t get_manager_memory_pool_size() const {
     return manager_memory_pool_size;
   }
+  /// Top-level database memory pool budget in bytes.
   size_t get_database_memory_pool_size() const {
     return database_memory_pool_size;
   }
+  /// Filesystem directory for database files (empty if unset).
   std::string get_db_path() const { return db_path; }
+  /// Whether data is written through to durable storage.
   bool is_persistence_enabled() const { return persistence_enabled; }
+  /// Whether structural or data validation checks run on operations.
   bool is_validation_enabled() const { return validation_enabled; }
+  /// Whether temporal versioning (copy-on-write for time travel) is active.
   bool is_versioning_enabled() const { return versioning_enabled_; }
 };
 
+/// Fluent builder for \ref DatabaseConfig; initial field values match the
+/// constants in namespace defaults.
 class DatabaseConfigBuilder {
  private:
   DatabaseConfig config;
 
  public:
+  /// Starts from default capacities, pools, path, and flags.
   DatabaseConfigBuilder() = default;
 
+  /// Sets \ref DatabaseConfig::get_shard_capacity.
   DatabaseConfigBuilder &with_shard_capacity(const size_t capacity) {
     config.shard_capacity = capacity;
     return *this;
   }
 
+  /// Sets \ref DatabaseConfig::get_chunk_size.
   DatabaseConfigBuilder &with_chunk_size(const size_t size) {
     config.chunk_size = size;
     return *this;
   }
 
+  /// Sets \ref DatabaseConfig::get_shard_memory_pool_size (bytes).
   DatabaseConfigBuilder &with_shard_memory_pool_size(const size_t size) {
     config.shard_memory_pool_size = size;
     return *this;
   }
 
+  /// Sets \ref DatabaseConfig::get_manager_memory_pool_size (bytes).
   DatabaseConfigBuilder &with_manager_memory_pool_size(const size_t size) {
     config.manager_memory_pool_size = size;
     return *this;
   }
 
+  /// Sets \ref DatabaseConfig::get_database_memory_pool_size (bytes).
   DatabaseConfigBuilder &with_database_memory_pool_size(const size_t size) {
     config.database_memory_pool_size = size;
     return *this;
   }
 
+  /// Sets \ref DatabaseConfig::get_db_path.
   DatabaseConfigBuilder &with_db_path(const std::string &directory) {
     config.db_path = directory;
     return *this;
   }
 
+  /// Sets \ref DatabaseConfig::is_persistence_enabled.
   DatabaseConfigBuilder &with_persistence_enabled(const bool enabled) {
     config.persistence_enabled = enabled;
     return *this;
   }
 
+  /// Sets \ref DatabaseConfig::is_validation_enabled.
   DatabaseConfigBuilder &with_validation_enabled(const bool enabled) {
     config.validation_enabled = enabled;
     return *this;
   }
 
+  /// Sets \ref DatabaseConfig::is_versioning_enabled.
   DatabaseConfigBuilder &with_versioning_enabled(const bool enabled) {
     config.versioning_enabled_ = enabled;
     return *this;
   }
 
+  /// Scales shard, manager, and database memory pools by \p factor from each
+  /// per-layer default byte size.
   DatabaseConfigBuilder &with_memory_scale_factor(const double factor) {
     config.shard_memory_pool_size =
         static_cast<size_t>(defaults::SHARD_MEMORY_POOL_SIZE * factor);
@@ -119,9 +144,12 @@ class DatabaseConfigBuilder {
     return *this;
   }
 
+  /// Returns the configured snapshot; safe to call multiple times (copies out).
   [[nodiscard]] DatabaseConfig build() const { return config; }
 };
 
+/// Convenience entry point equivalent to a default-constructed \ref
+/// DatabaseConfigBuilder.
 inline DatabaseConfigBuilder make_config() { return {}; }
 
 }  // namespace tundradb

include/common/logger.hpp

@@ -12,13 +12,19 @@ namespace tundradb {
 
 enum class LogLevel { DEBUG, INFO, WARN, ERROR };
 
+/// Process-wide logging facade over spdlog: level, optional file sink, and
+/// source-location-aware messages.
 class Logger {
  public:
+  /// Returns the singleton used by the `log_*` helpers declared later in this
+  /// header.
   static Logger& get_instance() {
     static Logger instance;
     return instance;
   }
 
+  /// Maps \ref LogLevel to the spdlog global cutoff (messages below it are
+  /// dropped).
   void set_level(LogLevel level) {
     switch (level) {
       case LogLevel::DEBUG:
@@ -36,6 +42,8 @@ class Logger {
     }
   }
 
+  /// Current spdlog level coerced to \ref LogLevel (trace/off and similar map
+  /// to INFO).
   LogLevel get_level() {
     switch (spdlog::get_level()) {
       case spdlog::level::trace:
@@ -57,6 +65,8 @@ class Logger {
     }
   }
 
+  /// Replaces the default logger with an appending file sink at \p filename;
+  /// failures are reported with spdlog::error.
   void set_log_to_file(const std::string& filename) {
     try {
       auto file_sink =
@@ -69,65 +79,79 @@ class Logger {
     }
   }
 
+  /// DEBUG with explicit \p location (file basename and line appear in the log
+  /// line).
   template <typename... Args>
   void debug(const std::source_location& location,
              spdlog::format_string_t<Args...> fmt, Args&&... args) {
     log(spdlog::level::debug, location, fmt, std::forward<Args>(args)...);
   }
 
+  /// INFO with explicit \p location in the output pattern.
   template <typename... Args>
   void info(const std::source_location& location,
             spdlog::format_string_t<Args...> fmt, Args&&... args) {
     log(spdlog::level::info, location, fmt, std::forward<Args>(args)...);
   }
 
+  /// WARN with explicit \p location in the output pattern.
   template <typename... Args>
   void warn(const std::source_location& location,
             spdlog::format_string_t<Args...> fmt, Args&&... args) {
     log(spdlog::level::warn, location, fmt, std::forward<Args>(args)...);
   }
 
+  /// ERROR with explicit \p location in the output pattern.
   template <typename... Args>
   void error(const std::source_location& location,
              spdlog::format_string_t<Args...> fmt, Args&&... args) {
     log(spdlog::level::err, location, fmt, std::forward<Args>(args)...);
   }
 
+  /// DEBUG using \ref std::source_location::current for the callsite.
   template <typename... Args>
   void debug(spdlog::format_string_t<Args...> fmt, Args&&... args) {
     debug(std::source_location::current(), fmt, std::forward<Args>(args)...);
   }
 
+  /// INFO using \ref std::source_location::current for the callsite.
   template <typename... Args>
   void info(spdlog::format_string_t<Args...> fmt, Args&&... args) {
     info(std::source_location::current(), fmt, std::forward<Args>(args)...);
   }
 
+  /// WARN using \ref std::source_location::current for the callsite.
   template <typename... Args>
   void warn(spdlog::format_string_t<Args...> fmt, Args&&... args) {
     warn(std::source_location::current(), fmt, std::forward<Args>(args)...);
   }
 
+  /// ERROR using \ref std::source_location::current for the callsite.
   template <typename... Args>
   void error(spdlog::format_string_t<Args...> fmt, Args&&... args) {
     error(std::source_location::current(), fmt, std::forward<Args>(args)...);
   }
 
+  /// DEBUG for a plain string (no format placeholders); \p location defaults to
+  /// the callsite.
   void debug(const std::string& message, const std::source_location& location =
                                              std::source_location::current()) {
     debug(location, "{}", message);
   }
 
+  /// INFO for a plain string; \p location defaults to the callsite.
   void info(const std::string& message, const std::source_location& location =
                                             std::source_location::current()) {
     info(location, "{}", message);
   }
 
+  /// WARN for a plain string; \p location defaults to the callsite.
   void warn(const std::string& message, const std::source_location& location =
                                             std::source_location::current()) {
     warn(location, "{}", message);
   }
 
+  /// ERROR for a plain string; \p location defaults to the callsite.
   void error(const std::string& message, const std::source_location& location =
                                              std::source_location::current()) {
     error(location, "{}", message);
@@ -222,53 +246,69 @@ inline void log_error(
   Logger::get_instance().error(message, location);
 }
 
+/// Prefixes every emitted line (e.g. subsystem name) before forwarding to the
+/// global \ref Logger.
 class ContextLogger {
  public:
+  /// \p prefix is copied and prepended as `prefix + ": " + message` for each
+  /// log call.
   explicit ContextLogger(std::string prefix) : prefix_(std::move(prefix)) {}
 
+  /// DEBUG with format string; output includes the stored prefix.
   template <typename... Args>
   void debug(spdlog::format_string_t<Args...> fmt, Args&&... args) {
     std::string message =
         spdlog::fmt_lib::format(fmt, std::forward<Args>(args)...);
     log_debug(prefix_ + ": " + message);
   }
 
+  /// INFO with format string; output includes the stored prefix.
   template <typename... Args>
   void info(spdlog::format_string_t<Args...> fmt, Args&&... args) {
     std::string message =
         spdlog::fmt_lib::format(fmt, std::forward<Args>(args)...);
     log_info(prefix_ + ": " + message);
   }
 
+  /// WARN with format string; output includes the stored prefix.
   template <typename... Args>
   void warn(spdlog::format_string_t<Args...> fmt, Args&&... args) {
     std::string message =
         spdlog::fmt_lib::format(fmt, std::forward<Args>(args)...);
     log_warn(prefix_ + ": " + message);
   }
 
+  /// ERROR with format string; output includes the stored prefix.
   template <typename... Args>
   void error(spdlog::format_string_t<Args...> fmt, Args&&... args) {
     std::string message =
         spdlog::fmt_lib::format(fmt, std::forward<Args>(args)...);
     log_error(prefix_ + ": " + message);
   }
 
+  /// DEBUG for a plain string; \p location is forwarded to the underlying
+  /// global log call.
   void debug(const std::string& message, const std::source_location& location =
                                              std::source_location::current()) {
     log_debug(prefix_ + ": " + message, location);
   }
 
+  /// INFO for a plain string; \p location is forwarded to the underlying global
+  /// log call.
   void info(const std::string& message, const std::source_location& location =
                                             std::source_location::current()) {
     log_info(prefix_ + ": " + message, location);
   }
 
+  /// WARN for a plain string; \p location is forwarded to the underlying global
+  /// log call.
   void warn(const std::string& message, const std::source_location& location =
                                             std::source_location::current()) {
     log_warn(prefix_ + ": " + message, location);
   }
 
+  /// ERROR for a plain string; \p location is forwarded to the underlying
+  /// global log call.
   void error(const std::string& message, const std::source_location& location =
                                              std::source_location::current()) {
     log_error(prefix_ + ": " + message, location);