feat: enhance async order management system with detailed descriptions and examples across documentation.

Co-authored-by: Genie <[email protected]>

Author: TexasCoding

src/project_x_py/order_manager/__init__.py

@@ -1,12 +1,36 @@
 """
-Order Manager Module for ProjectX Trading Platform.
-
-This module provides comprehensive order management functionality including:
-- Order placement (market, limit, stop, trailing stop)
-- Order modification and cancellation
-- Bracket order strategies
-- Position-based order management
-- Real-time order tracking and monitoring
+Async order management for ProjectX trading.
+
+Overview:
+    This package provides the async OrderManager system for ProjectX, offering robust,
+    extensible order placement, modification, cancellation, tracking, and advanced
+    bracket/position management. Integrates with both API and real-time clients for
+    seamless trading workflows.
+
+Key Features:
+    - Unified async order placement (market, limit, stop, trailing, bracket)
+    - Modification/cancellation with tick-size alignment
+    - Position-based order and risk management
+    - Real-time tracking, event-driven callbacks, and statistics
+    - Modular design for strategy and bot development
+
+Example Usage:
+    ```python
+    from project_x_py import ProjectX
+    from project_x_py.order_manager import OrderManager
+
+    async with ProjectX.from_env() as client:
+        om = OrderManager(client)
+        await om.place_market_order("MNQ", 0, 1)  # Buy 1 contract at market
+    ```
+
+See Also:
+    - `order_manager.core.OrderManager`
+    - `order_manager.bracket_orders`
+    - `order_manager.order_types`
+    - `order_manager.position_orders`
+    - `order_manager.tracking`
+    - `order_manager.utils`
 """
 
 from project_x_py.order_manager.core import OrderManager

src/project_x_py/order_manager/bracket_orders.py

@@ -1,4 +1,31 @@
-"""Bracket order functionality for complex order strategies."""
+"""
+Async bracket order strategies for ProjectX.
+
+Overview:
+    Provides mixin logic for placing and managing bracket orders—sophisticated, three-legged
+    order strategies consisting of entry, stop loss, and take profit orders. Ensures risk
+    controls are established atomically and linked to positions for robust trade automation.
+
+Key Features:
+    - Place async bracket orders (entry, stop, target) as a single operation
+    - Price/side validation and position link management
+    - Automatic risk management: stops and targets managed with entry
+    - Integrates with core OrderManager and position tracking
+
+Example Usage:
+    ```python
+    # Assuming om is an instance of OrderManager
+    await om.place_bracket_order(
+        contract_id="MGC", side=0, size=1,
+        entry_price=2050.0, stop_loss_price=2040.0, take_profit_price=2070.0
+    )
+    ```
+
+See Also:
+    - `order_manager.core.OrderManager`
+    - `order_manager.position_orders`
+    - `order_manager.order_types`
+"""
 
 import logging
 from typing import TYPE_CHECKING

src/project_x_py/order_manager/core.py

@@ -1,8 +1,34 @@
 """
-Core OrderManager class for comprehensive order operations.
-
-This module provides the main OrderManager class that handles all order-related
-operations including placement, modification, cancellation, and tracking.
+Async OrderManager core for ProjectX trading.
+
+Overview:
+    Contains the main OrderManager class, orchestrating all async order operations
+    (placement, modification, cancellation, tracking) and integrating mixins for
+    bracket, position, and order type strategies. Provides thread-safe, eventful,
+    and real-time capable order workflows for automated and manual trading.
+
+Key Features:
+    - Unified async API for order lifecycle (market, limit, stop, trailing, OCO)
+    - Bracket and position-based order strategies
+    - Real-time tracking, event-driven callbacks, and statistics
+    - Price alignment, concurrent safety, and health metrics
+    - Extensible for custom bots and strategy engines
+
+Example Usage:
+    ```python
+    from project_x_py import ProjectX
+    from project_x_py.order_manager import OrderManager
+
+    async with ProjectX.from_env() as client:
+        om = OrderManager(client)
+        await om.place_limit_order("ES", 0, 1, 5000.0)
+    ```
+
+See Also:
+    - `order_manager.bracket_orders`
+    - `order_manager.position_orders`
+    - `order_manager.order_types`
+    - `order_manager.tracking`
 """
 
 import asyncio

src/project_x_py/order_manager/order_types.py

@@ -1,4 +1,29 @@
-"""Order placement methods for different order types."""
+"""
+Async order type placement mixin for ProjectX.
+
+Overview:
+    Implements mixin methods for placing specific order types (market, limit,
+    stop, trailing stop) in the async OrderManager system. Encapsulates order-type
+    validation, parameter handling, and delegates to the unified underlying API.
+
+Key Features:
+    - Async placement of market, limit, stop, and trailing stop orders
+    - Standardized argument validation and contract handling
+    - Integrates with bracket and position order mixins
+    - Returns model-typed responses for downstream logic
+
+Example Usage:
+    ```python
+    # Assuming om is an instance of OrderManager
+    await om.place_limit_order("MES", 1, 2, 5000.0)
+    await om.place_market_order("MGC", 0, 1)
+    ```
+
+See Also:
+    - `order_manager.core.OrderManager`
+    - `order_manager.bracket_orders`
+    - `order_manager.position_orders`
+"""
 
 import logging
 from typing import TYPE_CHECKING

src/project_x_py/order_manager/position_orders.py

@@ -1,4 +1,29 @@
-"""Position-related order management functionality."""
+"""
+Async position-based order management for ProjectX.
+
+Overview:
+    Provides mixin logic for managing orders at the position level: closing open positions,
+    adding stop losses/take profits, and synchronizing/canceling related orders as position
+    size changes. Enables robust, risk-aware trading automations.
+
+Key Features:
+    - Async close, stop loss, and take profit for open positions
+    - Automatic order/position tracking and synchronization
+    - Bulk cancellation and modification of position-related orders
+    - Integrates with order callbacks and bracket strategies
+
+Example Usage:
+    ```python
+    # Assuming om is an instance of OrderManager
+    await om.close_position("MNQ")
+    await om.add_stop_loss("MNQ", stop_price=2030.0)
+    ```
+
+See Also:
+    - `order_manager.core.OrderManager`
+    - `order_manager.bracket_orders`
+    - `order_manager.order_types`
+"""
 
 import logging
 from typing import TYPE_CHECKING, Any

src/project_x_py/order_manager/tracking.py

@@ -1,4 +1,30 @@
-"""Order tracking and real-time monitoring functionality."""
+"""
+Async order tracking and real-time monitoring for ProjectX.
+
+Overview:
+    Implements mixin logic for tracking order status, maintaining local state and cache,
+    and handling real-time updates from websocket events. Supports callback registration
+    for fills/cancels, cache queries, and system health validation.
+
+Key Features:
+    - Real-time tracking via websocket/callbacks and local cache
+    - Order-to-position relationship mapping
+    - Async event/callback system for fills, cancels, rejections
+    - Cache clearing, health/status reporting, and metrics
+    - Integrates with OrderManager main class
+
+Example Usage:
+    ```python
+    # Assuming om is an instance of OrderManager
+    await om.initialize(realtime_client)
+    tracked = await om.get_tracked_order_status("12345")
+    ```
+
+See Also:
+    - `order_manager.core.OrderManager`
+    - `order_manager.position_orders`
+    - `order_manager.utils`
+"""
 
 import asyncio
 import logging

src/project_x_py/order_manager/utils.py

@@ -1,4 +1,28 @@
-"""Utility functions for order management."""
+"""
+Order management utility functions for ProjectX.
+
+Overview:
+    Provides async/sync helpers for price alignment to instrument tick size, contract
+    resolution, and other utility operations used throughout the async OrderManager system.
+
+Key Features:
+    - Aligns prices to valid instrument tick size (async and sync)
+    - Resolves contract IDs to instrument metadata
+    - Precision rounding and validation helpers
+
+Example Usage:
+    ```python
+    # Aligning a price to tick size
+    aligned = align_price_to_tick(2052.17, 0.25)
+    # Resolving contract ID
+    details = await resolve_contract_id("MNQ", project_x_client)
+    ```
+
+See Also:
+    - `order_manager.core.OrderManager`
+    - `order_manager.tracking`
+    - `order_manager.position_orders`
+"""
 
 import logging
 from decimal import ROUND_HALF_UP, Decimal