📝 Add docstrings to pr1212

mooncake-store/include/tiered_cache/cache_tier.h

@@ -7,6 +7,73 @@
 
 #include "transfer_engine.h"
 
+/**
+ * @enum MemoryType
+ * @brief Physical storage medium type used by a cache tier.
+ */
+
+/**
+ * @brief Convert a MemoryType value to its string representation.
+ * @param type The MemoryType value to convert.
+ * @returns The string name of `type` ("DRAM", "NVME", or "UNKNOWN").
+ */
+
+/**
+ * @struct DataSource
+ * @brief Describes a source or reservation for data transfer operations.
+ *
+ * Fields:
+ * - `ptr`: pointer value (in-memory address) or file descriptor identifying the source.
+ * - `offset`: byte offset within the source (for files/SSD ranges).
+ * - `size`: size in bytes.
+ * - `type`: physical memory type of the source.
+ */
+
+/**
+ * @class CacheTier
+ * @brief Abstract interface representing a single cache tier (for example DRAM or NVMe).
+ */
+
+/**
+ * @brief Initialize the cache tier with its parent backend and transfer engine.
+ * @returns `true` if initialization succeeds, `false` otherwise.
+ */
+
+/**
+ * @brief Reserve free space of the given size without performing any data copy.
+ * @param data Output parameter that will be populated with allocation details (ptr/offset/size/type).
+ * @returns `true` if the allocation succeeds, `false` otherwise.
+ */
+
+/**
+ * @brief Release or roll back a previously allocated reservation described by `data`.
+ * @returns `true` if the free/rollback succeeds, `false` otherwise.
+ */
+
+/**
+ * @brief Retrieve the identifier for this tier.
+ * @returns The tier identifier.
+ */
+
+/**
+ * @brief Retrieve the total capacity of the tier in bytes.
+ * @returns The tier capacity in bytes.
+ */
+
+/**
+ * @brief Retrieve the current used bytes within the tier.
+ * @returns The tier usage in bytes.
+ */
+
+/**
+ * @brief Retrieve the MemoryType of this tier.
+ * @returns The tier's MemoryType.
+ */
+
+/**
+ * @brief Retrieve metadata tags associated with this tier.
+ * @returns A reference to the vector of tag strings.
+ */
 namespace mooncake {
 
 struct DataSource;
@@ -85,4 +152,4 @@ class CacheTier {
     TieredBackend* backend_ = nullptr;
 };
 
-}  // namespace mooncake
+}  // namespace mooncake

mooncake-store/include/tiered_cache/copier_registry.h

@@ -27,10 +27,59 @@ struct DirectPathRegistration {
 };
 
 /**
- * @brief A singleton registry for data copier functions.
+ * Singleton registry that collects data copier functions for different memory
+ * types and optional optimized direct copy paths.
  *
- * Modules can register their copy functions here during static initialization.
- * The DataCopierBuilder will then use this registry to construct a DataCopier.
+ * Modules register copy functions (typically via static initialization)
+ * and DataCopierBuilder queries this registry to assemble a DataCopier.
+ */
+
+/**
+ * Access the global CopierRegistry instance.
+ *
+ * @returns Reference to the global CopierRegistry instance.
+ */
+
+/**
+ * Register the to-DRAM and from-DRAM copy functions for a memory type.
+ *
+ * @param type Memory type being registered.
+ * @param to_dram Copy function that copies data from `type` to DRAM.
+ * @param from_dram Copy function that copies data from DRAM to `type`.
+ */
+
+/**
+ * Register an optimized direct copy function for copying between two memory
+ * types.
+ *
+ * @param src Source memory type.
+ * @param dest Destination memory type.
+ * @param func Copy function that copies from `src` to `dest`.
+ */
+
+/**
+ * Retrieve all registered memory type entries.
+ *
+ * @returns Reference to the vector of MemoryTypeRegistration entries.
+ */
+
+/**
+ * Retrieve all registered direct path entries.
+ *
+ * @returns Reference to the vector of DirectPathRegistration entries.
+ */
+
+/**
+ * Helper that registers a memory type's to/from DRAM copy functions during
+ * static initialization when instantiated as a static object.
+ */
+
+/**
+ * Construct a CopierRegistrar and register the provided copy functions.
+ *
+ * @param type Memory type to register.
+ * @param to_dram Copy function that copies data from `type` to DRAM.
+ * @param from_dram Copy function that copies data from DRAM to `type`.
  */
 class CopierRegistry {
    public:
@@ -51,7 +100,26 @@ class CopierRegistry {
     void RegisterDirectPath(MemoryType src, MemoryType dest, CopyFunction func);
 
     // These methods are used by the DataCopierBuilder to collect all
-    // registrations.
+    /**
+ * Retrieve registered memory-type copy registrations.
+ *
+ * @returns A reference to the vector of MemoryTypeRegistration entries stored
+ *          in the registry.
+ */
+/**
+ * Retrieve registered direct-copy path registrations.
+ *
+ * @returns A reference to the vector of DirectPathRegistration entries stored
+ *          in the registry.
+ */
+/**
+ * Register a memory type's to/from DRAM copy functions at static
+ * initialization time.
+ *
+ * @param type The MemoryType being registered.
+ * @param to_dram Copy function used to transfer data from the memory type to DRAM.
+ * @param from_dram Copy function used to transfer data from DRAM to the memory type.
+ */
     const std::vector<MemoryTypeRegistration>& GetMemoryTypeRegistrations()
         const;
     const std::vector<DirectPathRegistration>& GetDirectPathRegistrations()

mooncake-store/include/tiered_cache/data_copier.h

@@ -8,6 +8,62 @@
 #include <stdexcept>
 #include <vector>
 
+/**
+ * @brief Builder that constructs a validated DataCopier instance.
+ *
+ * Ensures that all MemoryType entries have required copy paths registered
+ * (copies to and from DRAM) before producing an immutable DataCopier.
+ */
+
+/**
+ * @brief Constructs a builder initialized from the global CopierRegistry.
+ *
+ * Copies all current registrations from the global registry into the
+ * builder's internal copy matrix.
+ */
+
+/**
+ * @brief Registers an explicit direct copy path between two memory types.
+ *
+ * The provided function will be preferred over a DRAM fallback for the
+ * given src_type -> dest_type pair. Can be used to add optimized or
+ * non-registered paths (e.g., for testing).
+ * @return Reference to this builder for chaining.
+ */
+
+/**
+ * @brief Builds and returns a validated, immutable DataCopier.
+ *
+ * Verifies that required copy paths exist for every MemoryType before
+ * constructing the DataCopier.
+ * @return A unique_ptr to the constructed DataCopier.
+ * @throws std::logic_error If a required to/from DRAM copy function is missing.
+ */
+
+/**
+ * @brief Utility that copies data between memory types, with DRAM fallback.
+ *
+ * Performs copies using registered direct paths when available; otherwise
+ * falls back to a two-step copy via a temporary DRAM buffer.
+ */
+
+/**
+ * @brief Copies data from src to dst.
+ *
+ * Attempts a direct copy for src.memory_type -> dst.memory_type; if no direct
+ * copier is registered, performs a two-step copy via DRAM.
+ * @param src Data source descriptor.
+ * @param dst Data destination descriptor.
+ * @return `true` if the copy succeeds, `false` otherwise.
+ */
+
+/**
+ * @brief Locates a registered copy function for the specified memory types.
+ *
+ * @param src_type Source memory type.
+ * @param dest_type Destination memory type.
+ * @return The registered CopyFunction if found, or an empty std::function otherwise.
+ */
 namespace mooncake {
 
 using CopyFunction =

mooncake-store/include/tiered_cache/tiered_backend.h

@@ -12,6 +12,154 @@
 #include "tiered_cache/cache_tier.h"
 #include "tiered_cache/data_copier.h"
 
+/**
+ * @struct TieredLocation
+ * @brief Identifies the physical storage location of a segment within a tier.
+ *
+ * Contains the tier identifier and the data source descriptor for that location.
+ */
+
+/**
+ * @struct TierView
+ * @brief Snapshot of a tier's current status for topology reporting.
+ *
+ * Includes tier id, memory type, capacity, usage, free space, priority, and
+ * associated metadata tags.
+ */
+
+/**
+ * @struct AllocationEntry
+ * @brief Control block that represents an active allocation.
+ *
+ * When the last reference to this entry is destroyed, the destructor invokes
+ * the backend to release the associated physical resource.
+ */
+
+/**
+ * @typedef AllocationHandle
+ * @brief Reference-counted handle to an AllocationEntry.
+ */
+
+/**
+ * @brief Callback invoked after a data copy to synchronize metadata.
+ *
+ * @param key The metadata key associated with the copied data.
+ * @param new_loc The new tiered location created by the copy.
+ * @return `true` if metadata synchronization succeeded, `false` otherwise.
+ */
+
+/**
+ * @class TieredBackend
+ * @brief Manages storage placement, access, and lifecycle across multiple tiers.
+ *
+ * Provides allocation, write, commit, retrieval, deletion, and cross-tier copy
+ * operations, while exposing tier introspection and an internal release hook
+ * used by allocation control blocks.
+ */
+
+/**
+ * @brief Initialize the backend with configuration and a transfer engine.
+ *
+ * @param root JSON configuration root.
+ * @param engine Transfer engine used for cross-tier data movement.
+ * @return `true` on successful initialization, `false` otherwise.
+ */
+
+/**
+ * @brief Reserve storage space and return a handle representing the allocation.
+ *
+ * If the returned handle is destroyed without being committed, the reserved
+ * space is automatically freed.
+ *
+ * @param size Number of bytes to allocate.
+ * @param preferred_tier Optional preferred tier id for placement.
+ * @return An AllocationHandle that represents the reserved location, or an
+ * empty handle on failure.
+ */
+
+/**
+ * @brief Write data from the provided source into the allocated location.
+ *
+ * @param source Descriptor of the data to write.
+ * @param handle Handle that identifies the target allocation.
+ * @return `true` if the write completes successfully, `false` otherwise.
+ */
+
+/**
+ * @brief Register an allocation under a metadata key to make it discoverable.
+ *
+ * If a replica for the same key already exists on the same tier, it is
+ * replaced. Multiple replicas across different tiers are supported.
+ *
+ * @param key Metadata key to register (e.g., segment id).
+ * @param handle AllocationHandle representing the data to register.
+ * @return `true` on successful registration, `false` otherwise.
+ */
+
+/**
+ * @brief Retrieve an allocation handle for a metadata key.
+ *
+ * When `tier_id` is specified, returns the replica on that tier if present.
+ * When `tier_id` is not specified, returns a replica from the highest-priority
+ * available tier.
+ *
+ * @param key Metadata key to look up.
+ * @param tier_id Optional tier id to prefer.
+ * @return AllocationHandle for the located replica, or an empty handle if not found.
+ */
+
+/**
+ * @brief Remove replicas for a metadata key from the local index.
+ *
+ * When `tier_id` is specified, removes only the replica on that tier. When not
+ * specified, removes all replicas and the key's entry.
+ *
+ * @param key Metadata key to remove.
+ * @param tier_id Optional tier id specifying which replica to remove.
+ * @return `true` on successful deletion (or if the specified replica did not exist),
+ * `false` on failure.
+ */
+
+/**
+ * @brief Create a new replica of a key's data on a destination tier.
+ *
+ * Adds a new replica on `dest_tier_id`; it does not remove the original
+ * replica. After the data copy completes, the provided sync callback is
+ * invoked to update metadata accordingly.
+ *
+ * @param key Metadata key for the data being copied.
+ * @param source Descriptor of the data source to copy from.
+ * @param dest_tier_id Destination tier id where the copy will be placed.
+ * @param sync_cb Callback invoked after the copy to synchronize metadata.
+ * @return `true` if the copy and subsequent synchronization succeeded, `false` otherwise.
+ */
+
+/**
+ * @brief Return a snapshot list of current tier views.
+ *
+ * @return A vector of TierView describing each configured tier's state.
+ */
+
+/**
+ * @brief Retrieve a pointer to the CacheTier instance for a given tier id.
+ *
+ * @param tier_id Identifier of the tier to retrieve.
+ * @return Pointer to the CacheTier, or `nullptr` if the tier id is unknown.
+ */
+
+/**
+ * @brief Access the DataCopier component used for cross-tier transfers.
+ *
+ * @return Reference to the backend's DataCopier instance.
+ */
+
+/**
+ * @brief Internal API used by AllocationEntry destructor to release a location.
+ *
+ * Releases the physical resources associated with `loc`.
+ *
+ * @param loc The tiered location to free.
+ */
 namespace mooncake {
 
 class TieredBackend;  // Forward declaration