refactor(docs): Documentation Overhaul

src/storage/mod.rs

@@ -1,10 +1,42 @@
 //! Trial storage backends.
 //!
-//! The [`Storage`] trait defines how completed trials are stored and
-//! accessed.  [`MemoryStorage`] keeps trials in memory (the default).
-//! With the `journal` feature enabled, [`JournalStorage`] appends
-//! trials to a JSONL file with file-level locking so multiple
-//! processes can safely share state.
+//! The [`Storage`] trait defines how completed trials are persisted and
+//! retrieved.  Every [`Study`](crate::Study) owns an `Arc<dyn Storage<V>>`
+//! so storage is transparently shared across threads.
+//!
+//! # Available backends
+//!
+//! | Backend | Description | Feature flag |
+//! |---------|-------------|-------------|
+//! | [`MemoryStorage`] | In-memory `Vec` behind a read-write lock (the default) | — |
+//! | [`JournalStorage`] | JSONL file with `fs2` file locking for multi-process sharing | `journal` |
+//!
+//! # When to swap backends
+//!
+//! The default [`MemoryStorage`] is sufficient for single-process studies
+//! where persistence is not needed.  Switch to [`JournalStorage`] when you
+//! want to:
+//!
+//! - **Resume** a study after a process restart.
+//! - **Share state** across multiple processes writing to the same file.
+//! - **Inspect** trial history in a human-readable JSONL file.
+//!
+//! # Implementing a custom backend
+//!
+//! Implement the [`Storage`] trait to plug in your own backend (e.g. a
+//! database).  The trait requires four methods: [`push`](Storage::push),
+//! [`trials_arc`](Storage::trials_arc), [`next_trial_id`](Storage::next_trial_id),
+//! and optionally [`refresh`](Storage::refresh) for external data sources.
+//!
+//! Inject your storage into a study via the builder:
+//!
+//! ```
+//! use optimizer::prelude::*;
+//! use optimizer::storage::MemoryStorage;
+//!
+//! let storage = MemoryStorage::<f64>::new();
+//! let study = Study::builder().minimize().storage(storage).build();
+//! ```
 
 #[cfg(feature = "journal")]
 mod journal;
@@ -26,7 +58,8 @@ use crate::sampler::CompletedTrial;
 /// default implementation is [`MemoryStorage`], which keeps trials in
 /// a plain `Vec` behind a read-write lock.
 ///
-/// Implementations must be safe to use from multiple threads.
+/// Implementations must be `Send + Sync` because a study may be shared
+/// across threads (e.g. via [`optimize_parallel`](crate::Study::optimize_parallel)).
 pub trait Storage<V>: Send + Sync {
     /// Append a completed trial to the store.
     fn push(&self, trial: CompletedTrial<V>);
@@ -38,14 +71,14 @@ pub trait Storage<V>: Send + Sync {
     /// lock for efficient, allocation-free access.
     fn trials_arc(&self) -> &Arc<RwLock<Vec<CompletedTrial<V>>>>;
 
-    /// Atomically returns the next unique trial ID.
+    /// Atomically return the next unique trial ID.
     ///
     /// Each call increments an internal counter so that consecutive
     /// calls always produce distinct IDs.
     fn next_trial_id(&self) -> u64;
 
     /// Reload from an external source (e.g. a file written by another
-    /// process).  Returns `true` if the in-memory buffer was updated.
+    /// process).  Return `true` if the in-memory buffer was updated.
     ///
     /// The default implementation is a no-op that returns `false`.
     fn refresh(&self) -> bool {