write more documentation

6 files changed, 75 insertions, 17 deletions

diff --git a/azalea/README.md b/azalea/README.md
index 2ea99de0..d9aa1574 100644
--- a/azalea/README.md
+++ b/azalea/README.md
@@ -1,3 +1,3 @@
-A framework for creating Minecraft bots.
+Azalea is a framework for creating Minecraft bots.
 
-Interally, it's just a wrapper over azalea-client, adding useful functions for making bots.
+Internally, it's just a wrapper over azalea-client, adding useful functions for making bots.
diff --git a/azalea/examples/craft_dig_straight_down.rs b/azalea/examples/craft_dig_straight_down.rs
index 89b11021..48e1fd22 100644
--- a/azalea/examples/craft_dig_straight_down.rs
+++ b/azalea/examples/craft_dig_straight_down.rs
@@ -11,7 +11,7 @@ struct State {
 #[tokio::main]
 async fn main() {
     let account = Account::offline("bot");
-    // or let bot = Account::microsoft("access token").await;
+    // or let bot = Account::microsoft("email").await;
 
     azalea::start(azalea::Options {
         account,
diff --git a/azalea/examples/echo.rs b/azalea/examples/echo.rs
index a5e27d56..a5280d8b 100644
--- a/azalea/examples/echo.rs
+++ b/azalea/examples/echo.rs
@@ -1,12 +1,13 @@
-use std::sync::Arc;
+//! A simple bot that repeats chat messages sent by other players.
 
 use azalea::{Account, Client, Event};
 use parking_lot::Mutex;
+use std::sync::Arc;
 
 #[tokio::main]
 async fn main() {
     let account = Account::offline("bot");
-    // or let account = Account::microsoft("access token").await;
+    // or let account = Account::microsoft("email").await;
 
     azalea::start(azalea::Options {
         account,
@@ -22,7 +23,7 @@ async fn main() {
 pub struct State {}
 
 async fn handle(bot: Client, event: Arc<Event>, state: Arc<Mutex<State>>) -> anyhow::Result<()> {
-    match event {
+    match *event {
         Event::Chat(m) => {
             if m.username == bot.username {
                 return Ok(()); // ignore our own messages
@@ -33,12 +34,6 @@ async fn handle(bot: Client, event: Arc<Event>, state: Arc<Mutex<State>>) -> any
             println!(m);
             bot.reconnect().await.unwrap();
         }
-        Event::HungerUpdate(h) => {
-            if !h.using_held_item() && h.hunger <= 17 {
-                bot.hold(azalea::ItemGroup::Food).await?;
-                bot.use_held_item().await?;
-            }
-        }
         _ => {}
     }
 
diff --git a/azalea/examples/pvp.rs b/azalea/examples/pvp.rs
index 9405cb6f..a2f070f0 100644
--- a/azalea/examples/pvp.rs
+++ b/azalea/examples/pvp.rs
@@ -1,7 +1,6 @@
-use std::sync::Arc;
-
 use azalea::{pathfinder, Account, Accounts, Client, Event};
 use parking_lot::Mutex;
+use std::sync::Arc;
 
 #[tokio::main]
 async fn main() {
diff --git a/azalea/src/lib.rs b/azalea/src/lib.rs
index 493745cb..19384761 100644
--- a/azalea/src/lib.rs
+++ b/azalea/src/lib.rs
@@ -1,3 +1,51 @@
+//! Azalea is a framework for creating Minecraft bots.
+//!
+//! Internally, it's just a wrapper over [`azalea_client`], adding useful
+//! functions for making bots. Because of this, lots of the documentation will
+//! refer to `azalea_client`. You can just replace these with `azalea` in your
+//! code, since everything from azalea_client is re-exported in azalea.
+//!
+//! # Examples
+//!
+//! ```rust,no_run
+//! //! A bot that logs chat messages sent in the server to the console.
+//!
+//! use azalea::prelude::*;
+//! use parking_lot::Mutex;
+//! use std::sync::Arc;
+//!
+//! #[tokio::main]
+//! async fn main() {
+//!     let account = Account::offline("bot");
+//!     // or Account::microsoft("example@example.com").await.unwrap();
+//!
+//!     azalea::start(azalea::Options {
+//!         account,
+//!         address: "localhost",
+//!         state: Arc::new(Mutex::new(State::default())),
+//!         plugins: vec![],
+//!         handle,
+//!     })
+//!     .await
+//!     .unwrap();
+//! }
+//!
+//! pub struct State {}
+//!
+//! async fn handle(bot: Client, event: Arc<Event>, state: Arc<Mutex<State>>) -> anyhow::Result<()> {
+//!     match *event {
+//!         Event::Chat(m) => {
+//!             println!(m.message().to_ansi(None));
+//!         }
+//!         _ => {}
+//!     }
+//!
+//!     Ok(())
+//! }
+//! ```
+//!
+//! [`azalea_client`]: https://crates.io/crates/azalea-client
+
 mod bot;
 pub mod prelude;
 
@@ -16,15 +64,27 @@ pub trait Plugin: Send + Sync {
 
 pub type HandleFn<Fut, S> = fn(Client, Arc<Event>, Arc<Mutex<S>>) -> Fut;
 
+/// The options that are passed to [`azalea::start`].
+///
+/// [`azalea::start`]: fn.start.html
 pub struct Options<S, A, Fut>
 where
     A: TryInto<ServerAddress>,
     Fut: Future<Output = Result<(), anyhow::Error>>,
 {
+    /// The address of the server that we're connecting to. This can be a
+    /// `&str`, [`ServerAddress`], or anything that implements
+    /// `TryInto<ServerAddress>`.
     pub address: A,
+    /// The account that's going to join the server,
     pub account: Account,
+    /// A list of plugins that are going to be used. Plugins are external
+    /// crates that add extra functionality to Azalea.
     pub plugins: Vec<Arc<dyn Plugin>>,
+    /// A struct that contains the data that you want your bot to remember
+    /// across events.
     pub state: Arc<Mutex<S>>,
+    /// The function that's called whenever we get an event.
     pub handle: HandleFn<Fut, S>,
 }
 
@@ -34,9 +94,10 @@ pub enum Error {
     InvalidAddress,
 }
 
-/// Join a Minecraft server.
+/// Join a server and start handling events. This function will run forever until
+/// it gets disconnected from the server.
 ///
-/// ```no_run
+/// ```rust,no_run
 /// azalea::start(azalea::Options {
 ///     account,
 ///     address: "localhost",
@@ -57,7 +118,7 @@ pub async fn start<
         Err(_) => return Err(Error::InvalidAddress),
     };
 
-    let (bot, mut rx) = options.account.join(&address).await.unwrap();
+    let (bot, mut rx) = Client::join(&options.account, address).await.unwrap();
 
     let state = options.state;
     let bot_plugin = Arc::new(bot::Plugin::default());
diff --git a/azalea/src/prelude.rs b/azalea/src/prelude.rs
index 7b3345b0..0ffb60b8 100644
--- a/azalea/src/prelude.rs
+++ b/azalea/src/prelude.rs
@@ -1 +1,4 @@
+//! The Azalea prelude.
+
 pub use crate::bot::BotTrait;
+pub use azalea_client::{Account, Client, Event};