Documented code

Added test cases

core/src/api/player.rs

@@ -1,3 +1,88 @@
+//! # Player Module
+//!
+//! This module defines the core `Player` trait that all poker bot implementations must
+//! implement. The Player trait provides the interface between the poker game engine
+//! and individual bot logic, enabling different AI strategies and human player interfaces.
+//!
+//! ## Player Trait Overview
+//!
+//! The `Player` trait defines the essential methods that a poker bot must implement:
+//! - **Initialization**: Setup with preferences and game parameters
+//! - **Hole Cards**: Receive private cards at the start of a hand
+//! - **Action Selection**: Choose appropriate actions during betting rounds
+//! - **Game Observation**: Receive information about game state changes
+//!
+//! ## Key Methods
+//!
+//! - `init()`: Initialize player with preferences and configuration
+//! - `hole_cards()`: Receive private hole cards for the current hand
+//! - `get_action()`: Return the player's chosen action when it's their turn
+//! - GameObserver methods: Receive updates about game state and other players' actions
+//!
+//! ## Implementation Requirements
+//!
+//! Any struct implementing `Player` must:
+//! - Handle initialization with arbitrary preferences
+//! - Process hole cards correctly
+//! - Return valid actions in `get_action()`
+//! - Implement all `GameObserver` methods appropriately
+//!
+//! ## Examples
+//!
+//! ### Basic Player Implementation
+//!
+//! ```rust
+//! use poker_api::api::player::Player;
+//! use poker_api::api::action::{Action, ActionType};
+//! use poker_api::api::card::Card;
+//! use poker_api::api::game_observer::GameObserver;
+//! use poker_api::api::preferences::Preferences;
+//!
+//! struct SimpleBot {
+//!     hole_cards: Option<(Card, Card)>,
+//! }
+//!
+//! impl Player for SimpleBot {
+//!     fn init(&mut self, _prefs: Box<dyn Preferences>) {
+//!         // Initialize bot with preferences
+//!     }
+//!
+//!     fn hole_cards(&mut self, c1: Card, c2: Card, _seat: usize) {
+//!         self.hole_cards = Some((c1, c2));
+//!     }
+//!
+//!     fn get_action(&mut self) -> Action {
+//!         // Simple logic: always call if cards are good
+//!         Action::call_action(0.0)
+//!     }
+//! }
+//!
+//! impl GameObserver for SimpleBot {
+//!     // Implement game observation methods...
+//! #   fn game_start(&mut self, _info: poker_api::api::game_info::GameInfo) {}
+//! #   fn game_end(&mut self) {}
+//! #   fn round_start(&mut self, _round: u8) {}
+//! #   fn round_end(&mut self) {}
+//! #   fn player_action(&mut self, _seat: usize, _action: Action) {}
+//! #   fn community_cards(&mut self, _cards: Vec<Card>) {}
+//! }
+//! ```
+//!
+//! ## Design Decisions
+//!
+//! - **Trait-Based Design**: Enables polymorphism between different bot types
+//! - **Event-Driven Architecture**: Players receive game state through observer pattern
+//! - **Minimal Interface**: Core methods required for any poker bot implementation
+//! - **Extensible Preferences**: Support for arbitrary bot configuration
+//! - **Action-Based Decisions**: Players return complete action objects
+//!
+//! ## Performance Characteristics
+//!
+//! - **Memory**: Minimal trait object overhead
+//! - **Method Calls**: O(1) trait method dispatch
+//! - **State Management**: Player manages internal state as needed
+//! - **Action Generation**: Variable time depending on bot complexity
+
 use crate::api::action::Action;
 use crate::api::card::Card;
 use crate::api::game_observer::GameObserver;