Add errors docs for common crate

Author: cjdsellers

crates/common/src/actor/data_actor.rs

@@ -17,6 +17,7 @@
 #![allow(dead_code)]
 #![allow(unused_variables)]
 #![allow(unused_imports)]
+#![allow(clippy::missing_errors_doc)]
 
 use std::{
     any::{Any, TypeId},

crates/common/src/cache/mod.rs

@@ -13,9 +13,11 @@
 //  limitations under the License.
 // -------------------------------------------------------------------------------------------------
 
-//! A common in-memory `Cache` for market and execution related data.
+//! In-memory cache for market and execution data, with optional persistent backing.
+//!
+//! Provides methods to load, query, and update cached data such as instruments, orders, and prices.
 
-// Allow missing error docs for a large number of cache methods for now.
+// Allow missing error documentation for now
 #![allow(clippy::missing_errors_doc)]
 
 pub mod config;
@@ -99,8 +101,11 @@ impl Default for Cache {
 }
 
 impl Cache {
-    /// Creates a new [`Cache`] instance.
+    /// Creates a new [`Cache`] instance with optional configuration and database adapter.
     #[must_use]
+    /// # Note
+    ///
+    /// Uses provided `CacheConfig` or defaults, and optional `CacheDatabaseAdapter` for persistence.
     pub fn new(
         config: Option<CacheConfig>,
         database: Option<Box<dyn CacheDatabaseAdapter>>,
@@ -139,7 +144,7 @@ impl Cache {
 
     // -- COMMANDS --------------------------------------------------------------------------------
 
-    /// Clears the current general cache and loads the general objects from the cache database.
+    /// Clears and reloads general entries from the database into the cache.
     ///
     /// # Errors
     ///
@@ -157,7 +162,7 @@ impl Cache {
         Ok(())
     }
 
-    /// Loads all caches (currencies, instruments, synthetics, accounts, orders, positions) from the database.
+    /// Loads all core caches (currencies, instruments, accounts, orders, positions) from the database.
     ///
     /// # Errors
     ///
@@ -177,7 +182,7 @@ impl Cache {
         Ok(())
     }
 
-    /// Clears the current currencies cache and loads currencies from the cache database.
+    /// Clears and reloads the currency cache from the database.
     ///
     /// # Errors
     ///
@@ -192,7 +197,7 @@ impl Cache {
         Ok(())
     }
 
-    /// Clears the current instruments cache and loads instruments from the cache database.
+    /// Clears and reloads the instrument cache from the database.
     ///
     /// # Errors
     ///
@@ -207,8 +212,7 @@ impl Cache {
         Ok(())
     }
 
-    /// Clears the current synthetic instruments cache and loads synthetic instruments from the cache
-    /// database.
+    /// Clears and reloads the synthetic instrument cache from the database.
     ///
     /// # Errors
     ///
@@ -226,7 +230,7 @@ impl Cache {
         Ok(())
     }
 
-    /// Clears the current accounts cache and loads accounts from the cache database.
+    /// Clears and reloads the account cache from the database.
     ///
     /// # Errors
     ///
@@ -244,7 +248,7 @@ impl Cache {
         Ok(())
     }
 
-    /// Clears the current orders cache and loads orders from the cache database.
+    /// Clears and reloads the order cache from the database.
     ///
     /// # Errors
     ///
@@ -259,7 +263,7 @@ impl Cache {
         Ok(())
     }
 
-    /// Clears the current positions cache and loads positions from the cache database.
+    /// Clears and reloads the position cache from the database.
     ///
     /// # Errors
     ///
@@ -1076,10 +1080,13 @@ impl Cache {
         }
     }
 
-    /// Adds a general object `value` (as bytes) to the cache at the given `key`.
+    /// Adds a raw bytes entry to the cache under the given key.
+    ///
+    /// The cache stores only raw bytes; interpretation is the caller's responsibility.
     ///
-    /// The cache is agnostic to what the bytes actually represent (and how it may be serialized),
-    /// which provides maximum flexibility.
+    /// # Errors
+    ///
+    /// Returns an error if persisting the entry to the backing database fails.
     pub fn add(&mut self, key: &str, value: Bytes) -> anyhow::Result<()> {
         check_valid_string(key, stringify!(key)).expect(FAILED);
         check_predicate_false(value.is_empty(), stringify!(value)).expect(FAILED);
@@ -1093,7 +1100,11 @@ impl Cache {
         Ok(())
     }
 
-    /// Adds the given order `book` to the cache.
+    /// Adds an `OrderBook` to the cache.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if persisting the order book to the backing database fails.
     pub fn add_order_book(&mut self, book: OrderBook) -> anyhow::Result<()> {
         log::debug!("Adding `OrderBook` {}", book.instrument_id);
 
@@ -1107,7 +1118,11 @@ impl Cache {
         Ok(())
     }
 
-    /// Adds the given `own_book` to the cache.
+    /// Adds an `OwnOrderBook` to the cache.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if persisting the own order book fails.
     pub fn add_own_order_book(&mut self, own_book: OwnOrderBook) -> anyhow::Result<()> {
         log::debug!("Adding `OwnOrderBook` {}", own_book.instrument_id);
 

crates/common/src/lib.rs

@@ -32,7 +32,7 @@
 #![deny(nonstandard_style)]
 #![deny(rustdoc::broken_intra_doc_links)]
 #![deny(missing_debug_implementations)]
-// #![deny(clippy::missing_errors_doc)]
+#![deny(clippy::missing_errors_doc)]
 
 // Uncomment once we've added trivial `Debug` impls everywhere
 // #![warn(missing_debug_implementations)]

crates/common/src/msgbus/mod.rs

@@ -428,7 +428,7 @@ impl MessageBus {
     ///
     /// # Errors
     ///
-    /// This function never returns an error.
+    /// This function never returns an error (TBD).
     pub const fn close(&self) -> anyhow::Result<()> {
         // TODO: Integrate the backing database
         Ok(())

crates/common/src/python/logging.rs

@@ -35,6 +35,11 @@ use crate::{
 
 #[pymethods]
 impl LoggerConfig {
+    /// Creates a [`LoggerConfig`] from a spec string.
+    ///
+    /// # Errors
+    ///
+    /// Returns a Python exception if the spec string is invalid.
     #[staticmethod]
     #[pyo3(name = "from_spec")]
     pub fn py_from_spec(spec: String) -> PyResult<Self> {
@@ -88,6 +93,11 @@ pub fn py_init_tracing() -> PyResult<()> {
 ///
 /// Should only be called once during an applications run, ideally at the
 /// beginning of the run.
+/// Initializes logging via Python interface.
+///
+/// # Errors
+///
+/// Returns a Python exception if logger initialization fails.
 #[pyfunction]
 #[pyo3(name = "init_logging")]
 #[allow(clippy::too_many_arguments)]

crates/common/src/python/xrate.rs

@@ -22,6 +22,15 @@ use ustr::Ustr;
 
 use crate::xrate::get_exchange_rate;
 
+/// Calculates the exchange rate between two currencies using provided bid and ask quotes.
+///
+/// # Errors
+///
+/// This function returns an error if:
+/// - `price_type` is equal to `Last` or `Mark` (cannot calculate from quotes).
+/// - `quotes_bid` or `quotes_ask` is empty.
+/// - `quotes_bid` and `quotes_ask` lengths are not equal.
+/// - The bid or ask side of a pair is missing.
 #[pyfunction]
 #[pyo3(name = "get_exchange_rate")]
 #[pyo3(signature = (from_currency, to_currency, price_type, quotes_bid, quotes_ask))]