Standardize errors section in doc comments

Author: cjdsellers

RELEASES.md

@@ -6,6 +6,7 @@ Released on TBD (UTC).
 - Added `PerContractFeeModel`, thanks @stefansimik
 - Added additional timestamp properties for `NautilusKernel`
 - Allow bar aggregators to persist after `request_aggregated_bars` (#2144), thanks @faysou
+- Handle directory and live streams to catalog (#2153), thanks @limx0
 
 ### Internal Improvements
 - Improved market order handling when no size available in book (now explicitly rejects)

nautilus_core/model/src/data/bar.rs

@@ -137,6 +137,16 @@ impl BarSpecification {
         Self::new_checked(step, aggregation, price_type).expect(FAILED)
     }
 
+    /// Creates a new [`BarSpecification`] instance with correctness checking.
+    ///
+    /// # Errors
+    ///
+    /// This function returns an error:
+    /// - If `step` is not positive (> 0).
+    ///
+    /// # Notes
+    ///
+    /// PyO3 requires a `Result` type for proper error handling and stacktrace printing in Python.
     pub fn new_checked(
         step: usize,
         aggregation: BarAggregation,
@@ -584,10 +594,10 @@ impl Bar {
     ///
     /// # Errors
     ///
-    /// This function returns an error if:
-    /// - `high` is not >= `low`.
-    /// - `high` is not >= `close`.
-    /// - `low` is not <= `close.
+    /// This function returns an error:
+    /// - If `high` is not >= `low`.
+    /// - If `high` is not >= `close`.
+    /// - If `low` is not <= `close.
     ///
     /// # Notes
     ///

nautilus_core/model/src/data/delta.rs

@@ -92,8 +92,8 @@ impl OrderBookDelta {
     ///
     /// # Errors
     ///
-    /// This function returns an error if:
-    /// - `action` is [`BookAction::Add`] or [`BookAction::Update`] and `size` is not positive (> 0).
+    /// This function returns an error:
+    /// - If `action` is [`BookAction::Add`] or [`BookAction::Update`] and `size` is not positive (> 0).
     ///
     /// # Notes
     ///

nautilus_core/model/src/data/quote.rs

@@ -91,9 +91,9 @@ impl QuoteTick {
     ///
     /// # Errors
     ///
-    /// This function returns an error if:
-    /// - `bid_price.precision` does not equal `ask_price.precision`.
-    /// - `bid_size.precision` does not equal `ask_size.precision`.
+    /// This function returns an error:
+    /// - If `bid_price.precision` does not equal `ask_price.precision`.
+    /// - If `bid_size.precision` does not equal `ask_size.precision`.
     ///
     /// # Notes
     ///

nautilus_core/model/src/data/trade.rs

@@ -91,8 +91,8 @@ impl TradeTick {
     ///
     /// # Errors
     ///
-    /// This function returns an error if:
-    /// - `size` is not positive (> 0).
+    /// This function returns an error:
+    /// - If `size` is not positive (> 0).
     ///
     /// # Notes
     ///

nautilus_core/model/src/identifiers/trade_id.rs

@@ -55,9 +55,9 @@ impl TradeId {
     ///
     /// # Errors
     ///
-    /// This function returns an error if:
-    /// - `value` is an invalid string (e.g., is empty or contains non-ASCII characters).
-    /// - `value` length exceeds 36 characters.
+    /// This function returns an error:
+    /// - If `value` is an invalid string (e.g., is empty or contains non-ASCII characters).
+    /// - If `value` length exceeds 36 characters.
     ///
     /// # Notes
     ///
@@ -72,9 +72,9 @@ impl TradeId {
     ///
     /// # Errors
     ///
-    /// This function returns an error if:
-    /// - `value` is an invalid string (e.g., is empty or contains non-ASCII characters).
-    /// - `value` length exceeds 36 characters.
+    /// This function returns an error:
+    /// - If `value` is an invalid string (e.g., is empty or contains non-ASCII characters).
+    /// - If `value` length exceeds 36 characters.
     pub fn new<T: AsRef<str>>(value: T) -> Self {
         Self::new_checked(value).expect(FAILED)
     }
@@ -85,11 +85,11 @@ impl TradeId {
     ///
     /// # Panics
     ///
-    /// This function panics if:
-    /// - The byte slice is empty or consists only of a single null byte.
-    /// - The byte slice exceeds 36 bytes and does not end with a null byte.
-    /// - The byte slice is exactly 37 bytes but the last byte is not null.
-    /// - The byte slice contains non-ASCII characters.
+    /// This function panics:
+    /// - If `value` is empty or consists only of a single null byte.
+    /// - If `value` exceeds 36 bytes and does not end with a null byte.
+    /// - If `value` is exactly 37 bytes but the last byte is not null.
+    /// - If `value` contains non-ASCII characters.
     pub fn from_bytes(value: &[u8]) -> anyhow::Result<Self> {
         check_slice_not_empty(value, "value")?;