write/update docs for several items

17 files changed, 78 insertions, 21 deletions

diff --git a/azalea-chat/README.md b/azalea-chat/README.md
index e79d273a..c213159e 100644
--- a/azalea-chat/README.md
+++ b/azalea-chat/README.md
@@ -1,4 +1,4 @@
-# Azalea Chat
+# `azalea-chat`
 
 Things for working with Minecraft formatted text components.
 
diff --git a/azalea-client/README.md b/azalea-client/README.md
index 6ec41a0c..73ef1769 100644
--- a/azalea-client/README.md
+++ b/azalea-client/README.md
@@ -2,4 +2,4 @@
 
 A library that can mimic everything that a normal Minecraft client can do.
 
-If you want to make a bot with higher-level functions, consider using the `azalea` crate instead.
+To make a bot with higher-level functions, consider using the `azalea` crate instead.
diff --git a/azalea-client/src/client.rs b/azalea-client/src/client.rs
index 3ba52395..598c9ed4 100644
--- a/azalea-client/src/client.rs
+++ b/azalea-client/src/client.rs
@@ -492,7 +492,7 @@ impl Client {
     ///
     /// This is necessary for data-driven registries like [`Enchantment`].
     ///
-    /// [`Enchantment`]: azalea_registry::Enchantment
+    /// [`Enchantment`]: azalea_registry::data::Enchantment
     pub fn resolve_registry_name(
         &self,
         registry: &impl ResolvableDataRegistry,
@@ -507,7 +507,7 @@ impl Client {
     /// If you just want the value name, use [`Self::resolve_registry_name`]
     /// instead.
     ///
-    /// [`Enchantment`]: azalea_registry::Enchantment
+    /// [`Enchantment`]: azalea_registry::data::Enchantment
     pub fn with_resolved_registry<R: ResolvableDataRegistry, Ret>(
         &self,
         registry: R,
diff --git a/azalea-client/src/lib.rs b/azalea-client/src/lib.rs
index 6d216b2b..cff0b03a 100644
--- a/azalea-client/src/lib.rs
+++ b/azalea-client/src/lib.rs
@@ -1,10 +1,4 @@
-//! Significantly abstract [`azalea_protocol`] so it's actually useable for
-//! real clients. If you want to make bots, you should use the
-//! [`azalea`] crate instead.
-//!
-//! [`azalea_protocol`]: https://docs.rs/azalea-protocol
-//! [`azalea`]: https://docs.rs/azalea
-
+#![doc = include_str!("../README.md")]
 #![feature(error_generic_member_access)]
 #![feature(never_type)]
 
diff --git a/azalea-core/src/hit_result.rs b/azalea-core/src/hit_result.rs
index 2b269aba..e242c4b5 100644
--- a/azalea-core/src/hit_result.rs
+++ b/azalea-core/src/hit_result.rs
@@ -65,24 +65,33 @@ impl HitResult {
     }
 }
 
+/// The result of raycasting on the blocks in the world.
+///
+/// Also see [`HitResult`].
 #[derive(Clone, Debug, PartialEq)]
 pub struct BlockHitResult {
+    /// The exact position that the raycast ended at.
     pub location: Vec3,
     pub miss: bool,
 
     pub direction: Direction,
+    /// The block position that was hit.
+    ///
+    /// If [`Self::miss`] is true, then this will be the position that the
+    /// raycast ended at.
     pub block_pos: BlockPos,
     pub inside: bool,
     pub world_border: bool,
 }
 impl BlockHitResult {
-    pub fn miss(location: Vec3, direction: Direction, block_pos: BlockPos) -> Self {
+    /// Create a new [`BlockHitResult`] for when nothing was hit.
+    pub fn miss(location: Vec3, direction: Direction) -> Self {
         Self {
             location,
             miss: true,
 
             direction,
-            block_pos,
+            block_pos: BlockPos::from(location),
             inside: false,
             world_border: false,
         }
diff --git a/azalea-core/src/position.rs b/azalea-core/src/position.rs
index 502d5c20..cdf4b1b9 100644
--- a/azalea-core/src/position.rs
+++ b/azalea-core/src/position.rs
@@ -401,6 +401,7 @@ impl From<Vec3> for Vec3f32 {
 /// The coordinates of a block in the world.
 ///
 /// For entities (if the coordinates are floating-point), use [`Vec3`] instead.
+/// To convert a `BlockPos` to a `Vec3`, you'll usually want [`Self::center`].
 #[derive(Clone, Copy, Debug, Default, Eq, Hash, PartialEq)]
 pub struct BlockPos {
     pub x: i32,
@@ -444,6 +445,17 @@ impl BlockPos {
         (self.x.abs() + self.y.abs() + self.z.abs()) as u32
     }
 
+    /// Add or subtract `1` to one of this position's coordinates, depending on
+    /// the direction.
+    ///
+    /// ```
+    /// # use azalea_core::{position::BlockPos, direction::Direction};
+    /// let pos = BlockPos::new(10, 10, 10);
+    /// assert_eq!(
+    ///     pos.offset_with_direction(Direction::North),
+    ///     BlockPos::new(10, 10, 9)
+    /// );
+    /// ```
     pub fn offset_with_direction(self, direction: Direction) -> Self {
         self + direction.normal()
     }
diff --git a/azalea-crypto/src/offline.rs b/azalea-crypto/src/offline.rs
index 737555e8..b0e7c12b 100644
--- a/azalea-crypto/src/offline.rs
+++ b/azalea-crypto/src/offline.rs
@@ -1,6 +1,9 @@
+//! Offline-mode UUID generation.
+
 use md5::{Digest, Md5};
 use uuid::Uuid;
 
+/// Return what the offline-mode UUIDv3 for the given username would be.
 pub fn generate_uuid(username: &str) -> Uuid {
     uuid::Builder::from_md5_bytes(hash(format!("OfflinePlayer:{username}").as_bytes())).into_uuid()
 }
diff --git a/azalea-crypto/src/signing.rs b/azalea-crypto/src/signing.rs
index 57d5e1ad..c91146ea 100644
--- a/azalea-crypto/src/signing.rs
+++ b/azalea-crypto/src/signing.rs
@@ -1,3 +1,5 @@
+//! Chat signing, used in Minecraft to allow for messages to be reported.
+
 use std::time::{SystemTime, UNIX_EPOCH};
 
 use azalea_buf::{AzBuf, AzaleaWrite};
diff --git a/azalea-entity/src/attributes.rs b/azalea-entity/src/attributes.rs
index 6060af9f..b26f61ba 100644
--- a/azalea-entity/src/attributes.rs
+++ b/azalea-entity/src/attributes.rs
@@ -1,4 +1,6 @@
-//! See <https://minecraft.wiki/w/Attribute>.
+//! Attributes and modifiers for entities.
+//!
+//! Also see <https://minecraft.wiki/w/Attribute>.
 
 use std::collections::{HashMap, hash_map};
 
@@ -45,6 +47,8 @@ impl Attributes {
     }
 }
 
+/// An individual attribute for an entity, which may have any number of
+/// modifiers attached to it.
 #[derive(Clone, Debug)]
 pub struct AttributeInstance {
     pub base: f64,
@@ -52,6 +56,8 @@ pub struct AttributeInstance {
     // TODO: add cache
 }
 
+/// An error for when we try to call [`AttributeInstance::try_insert`] when the
+/// modifier is already present.
 #[derive(Clone, Debug, Error)]
 #[error("A modifier with this ID is already present.")]
 pub struct AlreadyPresentError;
diff --git a/azalea-language/src/lib.rs b/azalea-language/src/lib.rs
index 44d96f9c..df07accb 100644
--- a/azalea-language/src/lib.rs
+++ b/azalea-language/src/lib.rs
@@ -16,6 +16,9 @@ static STORAGE: LazyLock<Box<[(CompactString, CompactString)]>> = LazyLock::new(
     json.into_boxed_slice()
 });
 
+/// Get the string for the given translation ID.
+///
+/// This just does a lookup in Minecraft's `en_us.json` file.
 pub fn get(key: &str) -> Option<&str> {
     let key = CompactString::from(key);
     let storage = &*STORAGE;
diff --git a/azalea-physics/src/clip.rs b/azalea-physics/src/clip.rs
index cabcd2a6..b35857d3 100644
--- a/azalea-physics/src/clip.rs
+++ b/azalea-physics/src/clip.rs
@@ -126,11 +126,7 @@ pub fn clip(chunk_storage: &ChunkStorage, context: ClipContext) -> BlockHitResul
         },
         |context| {
             let vec = context.from - context.to;
-            BlockHitResult::miss(
-                context.to,
-                Direction::nearest(vec),
-                BlockPos::from(context.to),
-            )
+            BlockHitResult::miss(context.to, Direction::nearest(vec))
         },
     )
 }
diff --git a/azalea-physics/src/collision/blocks.rs b/azalea-physics/src/collision/blocks.rs
index 8dc01228..2622aeb7 100644
--- a/azalea-physics/src/collision/blocks.rs
+++ b/azalea-physics/src/collision/blocks.rs
@@ -14,7 +14,14 @@ use super::VoxelShape;
 use crate::collision::{self, Shapes};
 
 pub trait BlockWithShape {
+    /// The hitbox for blocks that's used when simulating physics.
     fn collision_shape(&self) -> &'static VoxelShape;
+    /// The hitbox for blocks that's used for determining whether we're looking
+    /// at it.
+    ///
+    /// This is often but not always the same as the collision shape. For
+    /// example, tall grass has a normal outline shape but an empty collision
+    /// shape.
     fn outline_shape(&self) -> &'static VoxelShape;
     /// Tells you whether the block has an empty shape.
     ///
diff --git a/azalea-world/src/chunk_storage.rs b/azalea-world/src/chunk_storage.rs
index 2e87fdf6..65dbbb7a 100644
--- a/azalea-world/src/chunk_storage.rs
+++ b/azalea-world/src/chunk_storage.rs
@@ -49,7 +49,16 @@ pub struct PartialChunkStorage {
 /// pointers.
 #[derive(Clone, Debug)]
 pub struct ChunkStorage {
+    /// The height of the world.
+    ///
+    /// To get the maximum y position (exclusive), you have to combine this with
+    /// [`Self::min_y`].
     pub height: u32,
+    /// The lowest y position in the world that can still have blocks placed on
+    /// it.
+    ///
+    /// This exists because in modern Minecraft versions, worlds can extend
+    /// below y=0.
     pub min_y: i32,
     pub map: IntMap<ChunkPos, Weak<RwLock<Chunk>>>,
 }
diff --git a/azalea-world/src/world.rs b/azalea-world/src/world.rs
index e4260aee..c2ba6749 100644
--- a/azalea-world/src/world.rs
+++ b/azalea-world/src/world.rs
@@ -169,10 +169,14 @@ pub struct Instance {
 }
 
 impl Instance {
+    /// Get the block at the given position, or `None` if it's outside of the
+    /// world that we have loaded.
     pub fn get_block_state(&self, pos: BlockPos) -> Option<BlockState> {
         self.chunks.get_block_state(pos)
     }
 
+    /// Similar to [`Self::get_block_state`], but returns data about the fluid
+    /// at the position, including for waterlogged blocks.
     pub fn get_fluid_state(&self, pos: BlockPos) -> Option<FluidState> {
         self.chunks.get_block_state(pos).map(FluidState::from)
     }
diff --git a/azalea/README.md b/azalea/README.md
index ca081f8e..8a02e7da 100644
--- a/azalea/README.md
+++ b/azalea/README.md
@@ -89,7 +89,7 @@ Azalea lets you create "swarms", which are a group of bots in the same world tha
 
 Azalea uses [Bevy ECS](https://docs.rs/bevy_ecs) internally to store information about the world and clients. Bevy plugins are more powerful than async handler functions, but more difficult to use. See [pathfinder](https://github.com/azalea-rs/azalea/blob/main/azalea/src/pathfinder/mod.rs) as an example of how to make a plugin. You can then enable a plugin by adding `.add_plugin(ExamplePlugin)` in your client/swarm builder.
 
-Everything in Azalea is implemented as a Bevy plugin, which means you can disable default behaviors (like, physics or chat signing) by disabling built-in plugins. See [`SwarmBuilder::new_without_plugins`](swarm::SwarmBuilder::new_without_plugins) to learn how to do that.
+Everything inside of Azalea is implemented as a Bevy plugin, which means you can disable default behaviors (like, physics or chat signing) by disabling built-in plugins. See [`SwarmBuilder::new_without_plugins`](swarm::SwarmBuilder::new_without_plugins) to learn how to do that.
 
 Also note that just because something is an entity in the ECS doesn't mean that it's a Minecraft entity. You can filter for that by having `With<MinecraftEntityId>` as a filter.
 
diff --git a/azalea/src/bot.rs b/azalea/src/bot.rs
index 3c262709..8410f0b1 100644
--- a/azalea/src/bot.rs
+++ b/azalea/src/bot.rs
@@ -86,10 +86,14 @@ fn stop_jumping(mut query: Query<(&mut Jumping, &mut Bot)>) {
     }
 }
 
+/// A trait that adds a few additional functions to [`Client`] that help with
+/// making bots.
 pub trait BotClientExt {
     /// Queue a jump for the next tick.
     fn jump(&self);
     /// Turn the bot's head to look at the coordinate in the world.
+    ///
+    /// To look at the center of a block, you should call [`BlockPos::center`].
     fn look_at(&self, pos: Vec3);
     /// Get a receiver that will receive a message every tick.
     fn get_tick_broadcaster(&self) -> tokio::sync::broadcast::Receiver<()>;
diff --git a/codegen/lib/code/shapes.py b/codegen/lib/code/shapes.py
index 59b0cb98..da23e20f 100644
--- a/codegen/lib/code/shapes.py
+++ b/codegen/lib/code/shapes.py
@@ -142,11 +142,19 @@ use crate::collision::{{self, Shapes}};
 use azalea_block::*;
 
 pub trait BlockWithShape {{
+    /// The hitbox for blocks that's used when simulating physics.
     fn collision_shape(&self) -> &'static VoxelShape;
+    /// The hitbox for blocks that's used for determining whether we're looking
+    /// at it.
+    ///
+    /// This is often but not always the same as the collision shape. For
+    /// example, tall grass has a normal outline shape but an empty collision
+    /// shape.
     fn outline_shape(&self) -> &'static VoxelShape;
     /// Tells you whether the block has an empty shape.
     ///
-    /// This is slightly more efficient than calling `shape()` and comparing against `EMPTY_SHAPE`.
+    /// This is slightly more efficient than calling `shape()` and comparing
+    /// against `EMPTY_SHAPE`.
     fn is_collision_shape_empty(&self) -> bool;
     fn is_collision_shape_full(&self) -> bool;
 }}