Add errors and panics docs for common crate

Author: cjdsellers

crates/common/src/actor/data_actor.rs

@@ -17,7 +17,6 @@
 #![allow(dead_code)]
 #![allow(unused_variables)]
 #![allow(unused_imports)]
-#![allow(clippy::missing_errors_doc)]
 
 use std::{
     any::{Any, TypeId},
@@ -1796,6 +1795,13 @@ impl DataActorCore {
 
     // -- REQUESTS --------------------------------------------------------------------------------
 
+    /// Request historical custom data of the given `data_type`.
+    ///
+    /// Returns a unique request ID to correlate subsequent [`CustomDataResponse`].
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the provided time range is invalid.
     pub fn request_data<A: DataActor>(
         &self,
         data_type: DataType,
@@ -1835,6 +1841,13 @@ impl DataActorCore {
         Ok(request_id)
     }
 
+    /// Request historical [`InstrumentResponse`] data for the given `instrument_id`.
+    ///
+    /// Returns a unique request ID to correlate subsequent [`InstrumentResponse`].
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the provided time range is invalid.
     pub fn request_instrument<A: DataActor>(
         &self,
         instrument_id: InstrumentId,
@@ -1875,6 +1888,13 @@ impl DataActorCore {
         Ok(request_id)
     }
 
+    /// Request historical [`InstrumentsResponse`] definitions for the optional `venue`.
+    ///
+    /// Returns a unique request ID to correlate subsequent [`InstrumentsResponse`].
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the provided time range is invalid.
     pub fn request_instruments<A: DataActor>(
         &self,
         venue: Option<Venue>,
@@ -1915,6 +1935,13 @@ impl DataActorCore {
         Ok(request_id)
     }
 
+    /// Request an [`OrderBook`] snapshot for the given `instrument_id`.
+    ///
+    /// Returns a unique request ID to correlate subsequent [`BookResponse`].
+    ///
+    /// # Errors
+    ///
+    /// This function never returns an error.
     pub fn request_book_snapshot<A: DataActor>(
         &self,
         instrument_id: InstrumentId,
@@ -1950,6 +1977,13 @@ impl DataActorCore {
         Ok(request_id)
     }
 
+    /// Request historical [`QuoteTick`] data for the given `instrument_id`.
+    ///
+    /// Returns a unique request ID to correlate subsequent [`QuotesResponse`].
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the provided time range is invalid.
     pub fn request_quotes<A: DataActor>(
         &self,
         instrument_id: InstrumentId,
@@ -1992,6 +2026,13 @@ impl DataActorCore {
         Ok(request_id)
     }
 
+    /// Request historical [`TradeTick`] data for the given `instrument_id`.
+    ///
+    /// Returns a unique request ID to correlate subsequent [`TradesResponse`].
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the provided time range is invalid.
     pub fn request_trades<A: DataActor>(
         &self,
         instrument_id: InstrumentId,
@@ -2034,6 +2075,13 @@ impl DataActorCore {
         Ok(request_id)
     }
 
+    /// Request historical [`Bar`] data for the given `bar_type`.
+    ///
+    /// Returns a unique request ID to correlate subsequent [`BarsResponse`].
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the provided time range is invalid.
     pub fn request_bars<A: DataActor>(
         &self,
         bar_type: BarType,

crates/common/src/actor/registry.rs

@@ -75,6 +75,11 @@ pub fn get_actor(id: &Ustr) -> Option<Rc<UnsafeCell<dyn Actor>>> {
     get_actor_registry().get(id)
 }
 
+/// Returns a mutable reference to the registered actor of type `T` for the given `id`.
+///
+/// # Panics
+///
+/// Panics if no actor with the specified `id` is found in the registry.
 #[allow(clippy::mut_from_ref)]
 pub fn get_actor_unchecked<T: Actor>(id: &Ustr) -> &mut T {
     let actor = get_actor(id).unwrap_or_else(|| panic!("Actor for {id} not found"));

crates/common/src/cache/database.rs

@@ -18,6 +18,8 @@
 // Under development
 #![allow(dead_code)]
 #![allow(unused_variables)]
+// TODO: Remove once error documentation is complete
+#![allow(clippy::missing_errors_doc)]
 
 use std::collections::HashMap;
 
@@ -155,10 +157,20 @@ pub trait CacheDatabaseAdapter {
     /// Returns an error if loading positions fails.
     async fn load_positions(&self) -> anyhow::Result<HashMap<PositionId, Position>>;
 
+    /// Loads all [`GreeksData`] from the cache.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if loading greeks data fails.
     async fn load_greeks(&self) -> anyhow::Result<HashMap<InstrumentId, GreeksData>> {
         Ok(HashMap::new())
     }
 
+    /// Loads all [`YieldCurveData`] from the cache.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if loading yield curve data fails.
     async fn load_yield_curves(&self) -> anyhow::Result<HashMap<String, YieldCurveData>> {
         Ok(HashMap::new())
     }

crates/common/src/cache/mod.rs

@@ -14,6 +14,7 @@
 // -------------------------------------------------------------------------------------------------
 
 // Under development
+// TODO: Remove once error documentation is complete
 #![allow(clippy::missing_errors_doc)]
 
 //! In-memory cache for market and execution data, with optional persistent backing.
@@ -1961,6 +1962,11 @@ impl Cache {
         query
     }
 
+    /// Retrieves orders corresponding to the given `client_order_ids`, optionally filtering by side.
+    ///
+    /// # Panics
+    ///
+    /// Panics if any `client_order_id` in the set is not found in the cache.
     fn get_orders_for_ids(
         &self,
         client_order_ids: &HashSet<ClientOrderId>,
@@ -1982,6 +1988,11 @@ impl Cache {
         orders
     }
 
+    /// Retrieves positions corresponding to the given `position_ids`, optionally filtering by side.
+    ///
+    /// # Panics
+    ///
+    /// Panics if any `position_id` in the set is not found in the cache.
     fn get_positions_for_ids(
         &self,
         position_ids: &HashSet<PositionId>,

crates/common/src/clock.rs

@@ -295,6 +295,11 @@ impl Clock for TestClock {
         self.default_callback = Some(callback);
     }
 
+    /// Returns the handler for the given `TimeEvent`.
+    ///
+    /// # Panics
+    ///
+    /// Panics if no event-specific or default callback has been registered for the event.
     fn get_handler(&self, event: TimeEvent) -> TimeEventHandlerV2 {
         // Get the callback from either the event-specific callbacks or default callback
         let callback = self
@@ -539,6 +544,11 @@ impl Clock for LiveClock {
         self.default_callback = Some(handler);
     }
 
+    /// # Panics
+    ///
+    /// This function panics if:
+    /// - The `clock_v2` feature is not enabled.
+    /// - The event does not have an associated handler (see trait documentation).
     #[allow(unused_variables)]
     fn get_handler(&self, event: TimeEvent) -> TimeEventHandlerV2 {
         #[cfg(not(feature = "clock_v2"))]

crates/common/src/ffi/enums.rs

@@ -29,6 +29,10 @@ pub extern "C" fn component_state_to_cstr(value: ComponentState) -> *const c_cha
 /// # Safety
 ///
 /// - Assumes `ptr` is a valid C string pointer.
+///
+/// # Panics
+///
+/// Panics if the input C string does not match a valid enum variant.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn component_state_from_cstr(ptr: *const c_char) -> ComponentState {
     let value = unsafe { cstr_as_str(ptr) };
@@ -46,6 +50,10 @@ pub extern "C" fn component_trigger_to_cstr(value: ComponentTrigger) -> *const c
 /// # Safety
 ///
 /// - Assumes `ptr` is a valid C string pointer.
+///
+/// # Panics
+///
+/// Panics if the input C string does not match a valid enum variant.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn component_trigger_from_cstr(ptr: *const c_char) -> ComponentTrigger {
     let value = unsafe { cstr_as_str(ptr) };
@@ -63,6 +71,10 @@ pub extern "C" fn log_level_to_cstr(value: LogLevel) -> *const c_char {
 /// # Safety
 ///
 /// - Assumes `ptr` is a valid C string pointer.
+///
+/// # Panics
+///
+/// Panics if the input C string does not match a valid enum variant.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn log_level_from_cstr(ptr: *const c_char) -> LogLevel {
     let value = unsafe { cstr_as_str(ptr) };
@@ -80,6 +92,10 @@ pub extern "C" fn log_color_to_cstr(value: LogColor) -> *const c_char {
 /// # Safety
 ///
 /// - Assumes `ptr` is a valid C string pointer.
+///
+/// # Panics
+///
+/// Panics if the input C string does not match a valid enum variant.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn log_color_from_cstr(ptr: *const c_char) -> LogColor {
     let value = unsafe { cstr_as_str(ptr) };

crates/common/src/ffi/timer.rs

@@ -38,6 +38,10 @@ pub struct TimeEventHandler {
 }
 
 impl From<TimeEventHandlerV2> for TimeEventHandler {
+    /// # Panics
+    ///
+    /// Panics if the provided `TimeEventHandlerV2` contains a Rust callback,
+    /// since only Python callbacks are supported by the legacy `TimeEventHandler`.
     fn from(value: TimeEventHandlerV2) -> Self {
         Self {
             event: value.event,

crates/common/src/lib.rs

@@ -33,6 +33,8 @@
 #![deny(rustdoc::broken_intra_doc_links)]
 #![deny(missing_debug_implementations)]
 #![deny(clippy::missing_errors_doc)]
+// TODO: Remove once panic documentation is complete
+// #![deny(clippy::missing_panics_doc)]
 
 // Uncomment once we've added trivial `Debug` impls everywhere
 // #![warn(missing_debug_implementations)]

crates/common/src/logging/headers.rs

@@ -140,6 +140,9 @@ fn python_package_version(package: &str) -> String {
 }
 
 #[cfg(not(feature = "python"))]
+/// # Panics
+///
+/// Panics if the `python` feature is not enabled.
 fn python_package_version(_package: &str) -> &str {
     panic!("`python` feature is not enabled");
 }
@@ -152,6 +155,9 @@ fn python_version() -> String {
 }
 
 #[cfg(not(feature = "python"))]
+/// # Panics
+///
+/// Panics if the `python` feature is not enabled.
 fn python_version() -> String {
     panic!("`python` feature is not enabled");
 }

crates/common/src/logging/mod.rs

@@ -169,6 +169,11 @@ pub const fn map_log_level_to_filter(log_level: LogLevel) -> LevelFilter {
     }
 }
 
+/// Parses a string into a [`LevelFilter`].
+///
+/// # Panics
+///
+/// Panics if the provided string is not a valid `LevelFilter`.
 #[must_use]
 pub fn parse_level_filter_str(s: &str) -> LevelFilter {
     let mut log_level_str = s.to_string().to_uppercase();
@@ -180,6 +185,11 @@ pub fn parse_level_filter_str(s: &str) -> LevelFilter {
 }
 
 #[must_use]
+/// Parses component-specific log levels from a JSON value map.
+///
+/// # Panics
+///
+/// Panics if a JSON value in the map is not a string representing a log level.
 pub fn parse_component_levels(
     original_map: Option<HashMap<String, serde_json::Value>>,
 ) -> HashMap<Ustr, LevelFilter> {

crates/common/src/msgbus/mod.rs

@@ -60,6 +60,10 @@ unsafe impl Sync for ShareableMessageBus {}
 static MESSAGE_BUS: OnceLock<ShareableMessageBus> = OnceLock::new();
 
 /// Sets the global message bus.
+///
+/// # Panics
+///
+/// Panics if a message bus has already been set.
 pub fn set_message_bus(msgbus: Rc<RefCell<MessageBus>>) {
     if MESSAGE_BUS.set(ShareableMessageBus(msgbus)).is_err() {
         panic!("Failed to set MessageBus");

crates/common/src/msgbus/stubs.rs

@@ -106,6 +106,11 @@ pub fn get_call_check_shareable_handler(id: Option<Ustr>) -> ShareableMessageHan
 }
 
 #[must_use]
+/// Returns whether the given `CallCheckMessageHandler` has been invoked at least once.
+///
+/// # Panics
+///
+/// Panics if the provided `handler` is not a `CallCheckMessageHandler`.
 pub fn check_handler_was_called(call_check_handler: ShareableMessageHandler) -> bool {
     call_check_handler
         .0
@@ -135,6 +140,11 @@ impl<T: Clone + 'static> MessageHandler for MessageSavingHandler<T> {
         self.id
     }
 
+    /// Handles an incoming message by saving it.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the provided `message` is not of the expected type `T`.
     fn handle(&self, message: &dyn Any) {
         let mut messages = self.messages.borrow_mut();
         match message.downcast_ref::<T>() {
@@ -161,6 +171,11 @@ pub fn get_message_saving_handler<T: Clone + 'static>(id: Option<Ustr>) -> Share
 }
 
 #[must_use]
+/// Retrieves the messages saved by a [`MessageSavingHandler`].
+///
+/// # Panics
+///
+/// Panics if the provided `handler` is not a `MessageSavingHandler<T>`.
 pub fn get_saved_messages<T: Clone + 'static>(handler: ShareableMessageHandler) -> Vec<T> {
     handler
         .0

crates/common/src/python/timer.rs

@@ -50,6 +50,10 @@ pub struct TimeEventHandler_Py {
 }
 
 impl From<TimeEventHandlerV2> for TimeEventHandler_Py {
+    /// # Panics
+    ///
+    /// Panics if the provided `TimeEventHandlerV2` contains a Rust callback,
+    /// since only Python callbacks are supported by this handler.
     fn from(value: TimeEventHandlerV2) -> Self {
         Self {
             event: value.event,

crates/common/src/timer.rs

@@ -149,6 +149,11 @@ impl Debug for TimeEventCallback {
 }
 
 impl TimeEventCallback {
+    /// Invokes the callback for the given `TimeEvent`.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the underlying Python callback invocation fails (e.g., raises an exception).
     pub fn call(&self, event: TimeEvent) {
         match self {
             #[cfg(feature = "python")]
@@ -199,6 +204,11 @@ impl TimeEventHandlerV2 {
         Self { event, callback }
     }
 
+    /// Executes the handler by invoking its callback for the associated event.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the underlying callback invocation fails (e.g., a Python callback raises an exception).
     pub fn run(self) {
         let Self { event, callback } = self;
         callback.call(event);