docs: add documentation to storage-api public types (#741) (#4007)

docs: add documentation to storage-api public types

Add doc comments to public structs, enums, and traits in
storage-api crate to improve documentation coverage.

Refs #741

crates/storage-api/src/bucket.rs

@@ -17,44 +17,69 @@ use std::fmt::Debug;
 use serde::{Deserialize, Serialize};
 use time::OffsetDateTime;
 
+/// Options for creating a new bucket.
 #[derive(Debug, Default, Serialize, Deserialize)]
 pub struct MakeBucketOptions {
+    /// Enable object lock for the bucket.
     pub lock_enabled: bool,
+    /// Enable versioning for the bucket.
     pub versioning_enabled: bool,
+    /// Force creation even if bucket already exists.
     pub force_create: bool,
+    /// Optional creation timestamp.
     pub created_at: Option<OffsetDateTime>,
+    /// Skip acquiring namespace lock.
     pub no_lock: bool,
 }
 
+/// Operation to perform on a bucket during site replication delete.
 #[derive(Debug, Default, Clone, PartialEq)]
 pub enum SRBucketDeleteOp {
+    /// No operation.
     #[default]
     NoOp,
+    /// Mark the bucket for deletion.
     MarkDelete,
+    /// Purge the bucket and all its contents.
     Purge,
 }
 
+/// Options for deleting a bucket.
 #[derive(Debug, Default, Clone)]
 pub struct DeleteBucketOptions {
+    /// Skip acquiring namespace lock.
     pub no_lock: bool,
+    /// Do not recreate bucket on failure.
     pub no_recreate: bool,
+    /// Force deletion even if bucket is not empty.
     pub force: bool,
+    /// Site replication delete operation.
     pub srdelete_op: SRBucketDeleteOp,
 }
 
+/// Options for querying bucket information.
 #[derive(Debug, Default, Serialize, Deserialize)]
 pub struct BucketOptions {
+    /// Include deleted buckets in results.
     pub deleted: bool,
+    /// Use cached bucket information.
     pub cached: bool,
+    /// Skip loading bucket metadata.
     pub no_metadata: bool,
 }
 
+/// Information about a bucket.
 #[derive(Debug, Clone, Serialize, Deserialize, Default)]
 pub struct BucketInfo {
+    /// Bucket name.
     pub name: String,
+    /// Creation timestamp.
     pub created: Option<OffsetDateTime>,
+    /// Deletion timestamp (if deleted).
     pub deleted: Option<OffsetDateTime>,
+    /// Whether versioning is enabled.
     pub versioning: bool,
+    /// Whether object locking is enabled.
     pub object_locking: bool,
 }
 

crates/storage-api/src/error.rs

@@ -14,8 +14,13 @@
 
 //! Stable storage error contracts shared across storage consumers.
 
+/// Result type alias for storage operations.
 pub type StorageResult<T, E = StorageErrorCode> = core::result::Result<T, E>;
 
+/// Error codes for storage operations.
+///
+/// These codes provide a stable, cross-crate error classification
+/// that can be serialized and transmitted between nodes.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum StorageErrorCode {
     Io,

crates/storage-api/src/observability.rs

@@ -18,45 +18,68 @@ use serde::{Deserialize, Serialize};
 
 use crate::{CapabilitySnapshotError, CapabilityStatus};
 
+/// Snapshot of observability capabilities and state.
 #[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct ObservabilitySnapshot {
+    /// Runtime telemetry capabilities.
     pub runtime_telemetry: CapabilityStatus,
+    /// Userspace profiling capabilities.
     pub userspace_profiling: UserspaceProfilingCapability,
+    /// Memory sampling state.
     pub memory_sampling: MemorySamplingState,
+    /// Platform support information.
     pub platform: PlatformSupport,
 }
 
+/// Capabilities for userspace profiling.
 #[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct UserspaceProfilingCapability {
+    /// CPU profiling capability.
     pub cpu: CapabilityStatus,
+    /// Memory profiling capability.
     pub memory: CapabilityStatus,
+    /// Continuous CPU profiling capability.
     pub continuous_cpu: CapabilityStatus,
+    /// Periodic CPU profiling capability.
     pub periodic_cpu: CapabilityStatus,
 }
 
+/// State of memory sampling capabilities.
 #[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct MemorySamplingState {
+    /// Process-level memory sampling.
     pub process: CapabilityStatus,
+    /// System-level memory sampling.
     pub system: CapabilityStatus,
+    /// Cgroup-level memory sampling.
     pub cgroup: CapabilityStatus,
 }
 
+/// Platform support information.
 #[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct PlatformSupport {
+    /// Target triple (e.g., x86_64-unknown-linux-gnu).
     pub target_triple: Option<String>,
+    /// Operating system.
     pub os: Option<String>,
+    /// Architecture.
     pub arch: Option<String>,
+    /// Memory allocator capability.
     pub allocator: CapabilityStatus,
+    /// eBPF support.
     pub ebpf: CapabilityStatus,
+    /// NUMA support.
     pub numa: CapabilityStatus,
 }
 
+/// Provider for observability snapshots.
 #[async_trait::async_trait]
 pub trait ObservabilitySnapshotProvider: Send + Sync + Debug {
+    /// Get a snapshot of observability capabilities and state.
     async fn observability_snapshot(&self) -> Result<ObservabilitySnapshot, CapabilitySnapshotError>;
 }