improved docs

azalea-client/src/client.rs

@@ -135,7 +135,9 @@ pub enum HandleError {
 impl Client {
     /// Connect to a Minecraft server.
     ///
-    /// To change the render distance and other settings, use [`Client::set_client_information`].
+    /// To change the render distance and other settings, use
+    /// [`Client::set_client_information`]. To watch for events like packets
+    /// sent by the server, use the `rx` variable this function returns.
     ///
     /// # Examples
     ///
@@ -145,7 +147,7 @@ impl Client {
     /// #[tokio::main]
     /// async fn main() -> Box<dyn std::error::Error> {
     ///     let account = Account::offline("bot");
-    ///     let client = Client::join(&account, "localhost").await?;
+    ///     let (client, rx) = Client::join(&account, "localhost").await?;
     ///     client.chat("Hello, world!").await?;
     ///     client.shutdown().await?;
     /// }
@@ -583,9 +585,10 @@ impl Client {
                 if let Err(e) = client
                     .dimension
                     .lock()
-                    .replace_with_packet_data(&pos, &mut Cursor::new(&p.chunk_data.data)) {
-                        error!("Couldn't set chunk data: {}", e);
-                    }
+                    .replace_with_packet_data(&pos, &mut Cursor::new(&p.chunk_data.data))
+                {
+                    error!("Couldn't set chunk data: {}", e);
+                }
             }
             ClientboundGamePacket::LightUpdate(_p) => {
                 // debug!("Got light update packet {:?}", p);

azalea-client/src/lib.rs

@@ -1,5 +1,5 @@
 //! Significantly abstract [`azalea_protocol`] so it's actually useable for
-//! real clients. If you want to make bots, however, you should use the
+//! real clients. If you want to make bots, you should use the
 //! [`azalea`] crate instead.
 //!
 //! [`azalea_protocol`]: https://crates.io/crates/azalea-protocol

azalea-protocol/src/connect.rs

@@ -1,4 +1,4 @@
-//! Create connections that communicate with a remote server or client.
+//! Connect to remote servers/clients.
 
 use crate::packets::game::{ClientboundGamePacket, ServerboundGamePacket};
 use crate::packets::handshake::{ClientboundHandshakePacket, ServerboundHandshakePacket};
@@ -11,7 +11,7 @@ use crate::write::write_packet;
 use azalea_auth::sessionserver::SessionServerError;
 use azalea_crypto::{Aes128CfbDec, Aes128CfbEnc};
 use bytes::BytesMut;
-use log::{info, error};
+use log::{error, info};
 use std::fmt::Debug;
 use std::marker::PhantomData;
 use std::net::SocketAddr;
@@ -116,6 +116,7 @@ impl<R> ReadConnection<R>
 where
     R: ProtocolPacket + Debug,
 {
+    /// Read a packet from the stream.
     pub async fn read(&mut self) -> Result<R, ReadPacketError> {
         read_packet::<R, _>(
             &mut self.read_stream,

azalea-protocol/src/lib.rs

@@ -6,6 +6,8 @@
 //!
 //! [`azalea`]: https://crates.io/crates/azalea
 //! [`azalea_client`]: https://crates.io/crates/azalea-client
+//!
+//! See [`crate::connect::Connection`] for an example.
 
 // these two are necessary for thiserror backtraces
 #![feature(error_generic_member_access)]
@@ -57,15 +59,6 @@ impl<'a> TryFrom<&'a str> for ServerAddress {
     }
 }
 
-#[cfg(feature = "connecting")]
-pub async fn connect(address: ServerAddress) -> Result<(), Box<dyn std::error::Error>> {
-    use log::debug;
-
-    let resolved_address = resolver::resolve_address(&address).await;
-    debug!("Resolved address: {:?}", resolved_address);
-    Ok(())
-}
-
 #[cfg(test)]
 mod tests {
     use std::io::Cursor;

azalea-protocol/src/read.rs

@@ -1,3 +1,5 @@
+//! Read packets from a stream.
+
 use crate::packets::ProtocolPacket;
 use azalea_buf::BufReadError;
 use azalea_buf::McBufVarReadable;
@@ -157,6 +159,8 @@ pub enum DecompressionError {
     AboveCompressionThreshold { size: u32, maximum: u32 },
 }
 
+/// Get the decompressed bytes from a packet. It must have been decrypted
+/// first.
 fn compression_decoder(
     stream: &mut Cursor<&[u8]>,
     compression_threshold: u32,
@@ -192,6 +196,12 @@ fn compression_decoder(
     Ok(decoded_buf)
 }
 
+/// Read a single packet from a stream.
+///
+/// The buffer is required because servers may send multiple packets in the
+/// same frame, so we need to store the packet data that's left to read.
+///
+/// The current protocol state must be passed as a generic.
 pub async fn read_packet<'a, P: ProtocolPacket + Debug, R>(
     stream: &'a mut R,
     buffer: &mut BytesMut,

azalea-protocol/src/resolver.rs

@@ -1,3 +1,5 @@
+//! Resolve IPs from hostnames.
+
 use crate::ServerAddress;
 use async_recursion::async_recursion;
 use std::net::{IpAddr, SocketAddr};

azalea-protocol/src/write.rs

@@ -1,3 +1,5 @@
+//! Write packets to a stream.
+
 use crate::{packets::ProtocolPacket, read::MAXIMUM_UNCOMPRESSED_LENGTH};
 use async_compression::tokio::bufread::ZlibEncoder;
 use azalea_buf::McBufVarWritable;
@@ -6,10 +8,11 @@ use std::fmt::Debug;
 use thiserror::Error;
 use tokio::io::{AsyncReadExt, AsyncWrite, AsyncWriteExt};
 
-fn frame_prepender(data: &mut Vec<u8>) -> Result<Vec<u8>, std::io::Error> {
+/// Prepend the length of the packet to it.
+fn frame_prepender(mut data: Vec<u8>) -> Result<Vec<u8>, std::io::Error> {
     let mut buf = Vec::new();
     (data.len() as u32).var_write_into(&mut buf)?;
-    buf.append(data);
+    buf.append(&mut data);
     Ok(buf)
 }
 
@@ -82,7 +85,7 @@ where
     if let Some(threshold) = compression_threshold {
         buf = compression_encoder(&buf, threshold).await.unwrap();
     }
-    buf = frame_prepender(&mut buf).unwrap();
+    buf = frame_prepender(buf).unwrap();
     // if we were given a cipher, encrypt the packet
     if let Some(cipher) = cipher {
         azalea_crypto::encrypt_packet(cipher, &mut buf);