From 0569ffd2d85585eb69de9068ab3f62e768bce4e7 Mon Sep 17 00:00:00 2001
From: mat <git@matdoes.dev>
Date: Mon, 15 Dec 2025 14:59:26 +0700
Subject: write/update docs for several items

---
 azalea-core/src/hit_result.rs | 13 +++++++++++--
 azalea-core/src/position.rs   | 12 ++++++++++++
 2 files changed, 23 insertions(+), 2 deletions(-)

(limited to 'azalea-core')

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()
     }
-- 
cgit v1.2.3