From 9ab70cb8f36a077445448f6e62191864e08fd0ce Mon Sep 17 00:00:00 2001
From: James Richey <49895469+j-richey@users.noreply.github.com>
Date: Sun, 8 Dec 2019 20:13:58 -0800
Subject: [PATCH] Update documentation with more examples

The updated documentation includes a full game played by two AI
opponents.
---
 src/ai.rs  | 35 +++++++++++++++++++++++++++++++++--
 src/lib.rs | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 83 insertions(+), 2 deletions(-)

diff --git a/src/ai.rs b/src/ai.rs
index 3842635..69860cb 100644
--- a/src/ai.rs
+++ b/src/ai.rs
@@ -1,4 +1,18 @@
 //! Provides functionality for creating single player games.
+//!
+//! # Examples
+//! ```
+//! use open_ttt_lib::ai;
+//! use open_ttt_lib::game;
+//!
+//! let game = game::Game::new();
+//! let ai_opponent = ai::Opponent::new(0.0);
+//!
+//! match ai_opponent.get_move(&game) {
+//!     Some(position) => assert!(game.can_move(position)),
+//!     None => panic!("The game is over so the AI opponent cannot do a move."),
+//! };
+//! ```
 
 use rand::seq::SliceRandom;
 use rand::Rng;
@@ -89,9 +103,10 @@ impl Opponent {
     /// let game = game::Game::new();
     /// let ai_opponent = ai::Opponent::new(0.0);
     ///
-    /// let position_map = ai_opponent.evaluate_game(&game);
+    /// let outcomes = ai_opponent.evaluate_game(&game);
     ///
-    /// for (position, outcome) in position_map {
+    /// // Display the outcome for each position.
+    /// for (position, outcome) in outcomes {
     ///     assert!(game.can_move(position));
     ///     println!("position: {:?} outcome: {:?}", position, outcome);
     /// }
@@ -245,6 +260,22 @@ impl AIPlayer {
 /// AI would rather have the game end in a draw than risk a loss. If there
 /// are multiple positions with the same outcome, one of the positions is
 /// picked at random.
+///
+/// # Examples
+/// ```
+/// use open_ttt_lib::ai;
+/// use open_ttt_lib::game;
+///
+/// let game = game::Game::new();
+/// let ai_opponent = ai::Opponent::new(0.0);
+///
+/// let outcomes = ai_opponent.evaluate_game(&game);
+///
+/// // Get the best position to use based on the outcomes.
+/// if let Some(position) = ai::best_position(&outcomes) {
+///     assert!(game.can_move(position));
+/// }
+/// ```
 pub fn best_position<S: BuildHasher>(
     outcomes: &HashMap<game::Position, Outcome, S>,
 ) -> Option<game::Position> {
diff --git a/src/lib.rs b/src/lib.rs
index 6143332..92ade16 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,4 +1,54 @@
 //! Provides common Tic Tac Toe logic and artificial intelligence algorithms.
+//!
+//! # Examples
+//! The example below creates a Tic Tac Toe game and two AI opponents to play
+//! the game.
+//! ```
+//! # use open_ttt_lib::game;
+//! #
+//! # fn main() -> Result<(), Box<game::Error>> {
+//! use open_ttt_lib::{ai, game};
+//!
+//! // Create a game and two AI opponents to play the game.
+//! let mut game = game::Game::new();
+//!
+//! // Rando picks random positions.
+//! let rando = ai::Opponent::new(1.0);
+//! // The flawless opponent cannot loose: it fully evaluates every possible
+//! // move and countermove in the game.
+//! let flawless_ai = ai::Opponent::new(0.0);
+//!
+//! // Have the opponents take turns making moves until the game is over.
+//! loop {
+//!     match game.state() {
+//!         game::State::PlayerXMove => {
+//!             println!("Rando playing as X turn:");
+//!             game.do_move(rando.get_move(&game).unwrap())?;
+//!         }
+//!         game::State::PlayerOMove => {
+//!             println!("Flawless AI playing as O turn:");
+//!             game.do_move(flawless_ai.get_move(&game).unwrap())?;
+//!         }
+//!         game::State::PlayerXWin(_) => {
+//!             println!("Game Over: Rando playing as X wins!");
+//!             break;
+//!         }
+//!         game::State::PlayerOWin(_) => {
+//!             println!("Game Over: Flawless AI playing as O wins!");
+//!             break;
+//!         }
+//!         game::State::CatsGame => {
+//!             println!("Game Over: cat's game.");
+//!             break;
+//!         }
+//!     };
+//!
+//!     // Print the game's the board.
+//!     println!("{}", game.board());
+//! }
+//! #   Ok(())
+//! # }
+//! ```
 
 pub mod ai;
 pub mod board;