write more documentation

6 files changed, 89 insertions, 21 deletions

diff --git a/azalea-client/src/account.rs b/azalea-client/src/account.rs
index fc34d6c4..f63d342e 100644
--- a/azalea-client/src/account.rs
+++ b/azalea-client/src/account.rs
@@ -1,13 +1,14 @@
 //! Connect to Minecraft servers.
 
-use crate::{client::JoinError, get_mc_dir, Client, Event};
-use azalea_protocol::ServerAddress;
-use tokio::sync::mpsc::UnboundedReceiver;
+use crate::get_mc_dir;
 use uuid::Uuid;
 
 /// Something that can join Minecraft servers.
+///
+/// To join a server using this account, use [`crate::Client::join`].
 #[derive(Clone, Debug)]
 pub struct Account {
+    /// The Minecraft username of the account.
     pub username: String,
     /// The access token for authentication. You can obtain one of these
     /// manually from azalea-auth.
@@ -15,7 +16,11 @@ pub struct Account {
     /// Only required for online-mode accounts.
     pub uuid: Option<uuid::Uuid>,
 }
+
 impl Account {
+    /// An offline account does not authenticate with Microsoft's servers, and
+    /// as such can only join offline mode servers. This is useful for testing
+    /// in LAN worlds.
     pub fn offline(username: &str) -> Self {
         Self {
             username: username.to_string(),
@@ -24,6 +29,10 @@ impl Account {
         }
     }
 
+    /// This will create an online-mode account by authenticating with
+    /// Microsoft's servers. Note that the email given is actually only used as
+    /// a key for the cache, but it's recommended to use the real email to
+    /// avoid confusion.
     pub async fn microsoft(email: &str) -> Result<Self, azalea_auth::AuthError> {
         let minecraft_dir = get_mc_dir::minecraft_dir().unwrap();
         let auth_result = azalea_auth::auth(
@@ -40,12 +49,4 @@ impl Account {
             uuid: Some(Uuid::parse_str(&auth_result.profile.id).expect("Invalid UUID")),
         })
     }
-
-    /// Joins the Minecraft server on the given address using this account.
-    pub async fn join(
-        &self,
-        address: &ServerAddress,
-    ) -> Result<(Client, UnboundedReceiver<Event>), JoinError> {
-        Client::join(self, address).await
-    }
 }
diff --git a/azalea-client/src/chat.rs b/azalea-client/src/chat.rs
index 6176357f..9e3d58a0 100644
--- a/azalea-client/src/chat.rs
+++ b/azalea-client/src/chat.rs
@@ -11,8 +11,9 @@ use crate::Client;
 
 impl Client {
     /// Sends chat message to the server. This only sends the chat packet and
-    /// not the command packet. The `chat` function handles checking whether
-    /// the message is a command and using the proper packet for you.
+    /// not the command packet. The [`Client::chat`] function handles checking whether
+    /// the message is a command and using the proper packet for you, so you
+    /// should use that instead.
     pub async fn send_chat_packet(&self, message: &str) -> Result<(), std::io::Error> {
         // TODO: chat signing
         let signature = sign_message();
@@ -54,6 +55,33 @@ impl Client {
         self.write_packet(packet).await
     }
 
+    /// Send a message in chat.
+    ///
+    /// # Examples
+    ///
+    /// ```rust,no_run
+    /// # use azalea::prelude::*;
+    /// # use parking_lot::Mutex;
+    /// # use std::sync::Arc;
+    /// # #[tokio::main]
+    /// # async fn main() {
+    /// #     let account = Account::offline("bot");
+    /// #     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<()> {
+    /// bot.chat("Hello, world!").await.unwrap();
+    /// # Ok(())
+    /// # }
+    /// ```
     pub async fn chat(&self, message: &str) -> Result<(), std::io::Error> {
         if message.chars().next() == Some('/') {
             self.send_command_packet(&message[1..]).await
diff --git a/azalea-client/src/client.rs b/azalea-client/src/client.rs
index a59c340b..fc4ff477 100644
--- a/azalea-client/src/client.rs
+++ b/azalea-client/src/client.rs
@@ -69,7 +69,7 @@ impl ChatPacket {
     }
 }
 
-/// A player that you can control that is currently in a Minecraft server.
+/// A player that you control that is currently in a Minecraft server.
 #[derive(Clone)]
 pub struct Client {
     game_profile: GameProfile,
@@ -106,6 +106,8 @@ pub enum JoinError {
     Io(#[from] io::Error),
     #[error("{0}")]
     SessionServer(#[from] azalea_auth::sessionserver::SessionServerError),
+    #[error("The given address could not be parsed into a ServerAddress")]
+    InvalidAddress,
 }
 
 #[derive(Error, Debug)]
@@ -119,12 +121,26 @@ pub enum HandleError {
 }
 
 impl Client {
-    /// Connect to a Minecraft server with an account.
+    /// Connect to a Minecraft server.
+    ///
+    /// ```rust,no_run
+    /// use azalea_client::Client;
+    ///
+    /// #[tokio::main]
+    /// async fn main() -> Box<dyn std::error::Error> {
+    ///     let account = Account::offline("bot");
+    ///     let client = Client::join(&account, "localhost").await?;
+    ///     client.chat("Hello, world!").await?;
+    ///     client.shutdown().await?;
+    /// }
+    /// ```
     pub async fn join(
         account: &Account,
-        address: &ServerAddress,
+        address: impl TryInto<ServerAddress>,
     ) -> Result<(Self, UnboundedReceiver<Event>), JoinError> {
-        let resolved_address = resolver::resolve_address(address).await?;
+        let address: ServerAddress = address.try_into().map_err(|_| JoinError::InvalidAddress)?;
+
+        let resolved_address = resolver::resolve_address(&address).await?;
 
         let mut conn = Connection::new(&resolved_address).await?;
 
diff --git a/azalea-client/src/lib.rs b/azalea-client/src/lib.rs
index 1ed30394..61d2d9ee 100755
--- a/azalea-client/src/lib.rs
+++ b/azalea-client/src/lib.rs
@@ -1,4 +1,9 @@
-//! Significantly abstract azalea-protocol so it's actually useable for bots.
+//! Significantly abstract [`azalea_protocol`] so it's actually useable for
+//! real clients. If you want to make bots, however, you should use the
+//! [`azalea`] crate instead.
+//!
+//! [`azalea_protocol`]: https://crates.io/crates/azalea-protocol
+//! [`azalea`]: https://crates.io/crates/azalea
 
 mod account;
 mod chat;
diff --git a/azalea-client/src/movement.rs b/azalea-client/src/movement.rs
index 85cf6bdd..93acf36f 100644
--- a/azalea-client/src/movement.rs
+++ b/azalea-client/src/movement.rs
@@ -155,6 +155,8 @@ impl Client {
         Ok(())
     }
 
+    /// Makes the bot do one physics tick. Note that this is already handled
+    /// automatically by the client.
     pub fn ai_step(&mut self) {
         self.tick_controls(None);
 
diff --git a/azalea-client/src/ping.rs b/azalea-client/src/ping.rs
index c59fb3ac..6817677e 100755
--- a/azalea-client/src/ping.rs
+++ b/azalea-client/src/ping.rs
@@ -1,4 +1,5 @@
-///! Ping Minecraft servers.
+//! Ping Minecraft servers.
+
 use azalea_protocol::{
     connect::{Connection, ConnectionError},
     packets::{
@@ -25,12 +26,27 @@ pub enum PingError {
     ReadPacket(#[from] azalea_protocol::read::ReadPacketError),
     #[error("{0}")]
     WritePacket(#[from] io::Error),
+    #[error("The given address could not be parsed into a ServerAddress")]
+    InvalidAddress,
 }
 
+/// Ping a Minecraft server.
+///
+/// ```
+/// use azalea_client::ping;
+///
+/// #[tokio::main]
+/// async fn main() {
+///     let response = ping::ping_server("play.hypixel.net").await.unwrap();
+///     println!("{}", response.description.to_ansi(None));
+/// }
+/// ```
 pub async fn ping_server(
-    address: &ServerAddress,
+    address: impl TryInto<ServerAddress>,
 ) -> Result<ClientboundStatusResponsePacket, PingError> {
-    let resolved_address = resolver::resolve_address(address).await?;
+    let address: ServerAddress = address.try_into().map_err(|_| PingError::InvalidAddress)?;
+
+    let resolved_address = resolver::resolve_address(&address).await?;
 
     let mut conn = Connection::new(&resolved_address).await?;