2 files changed, 15 insertions, 11 deletions

diff --git a/azalea-block/src/block_state.rs b/azalea-block/src/block_state.rs
index a954c333..e3f894bf 100644
--- a/azalea-block/src/block_state.rs
+++ b/azalea-block/src/block_state.rs
@@ -25,14 +25,14 @@ pub type BlockStateIntegerRepr = u16;
 /// [`BlockStateIntegerRepr`].
 #[derive(Copy, Clone, PartialEq, Eq, Default, Hash)]
 pub struct BlockState {
-    /// The protocol ID for the block state. IDs may change every
-    /// version, so you shouldn't hard-code them or store them in databases.
     id: BlockStateIntegerRepr,
 }
 
 impl BlockState {
     /// A shortcut for getting the air block state, since it always has an ID of
     /// 0.
+    ///
+    /// This does not include the other types of air like cave air.
     pub const AIR: BlockState = BlockState { id: 0 };
 
     /// Create a new BlockState and panic if the block is not a valid state.
@@ -53,15 +53,18 @@ impl BlockState {
         state_id <= Self::MAX_STATE
     }
 
-    /// Returns true if the block is air. This only checks for normal air, not
-    /// other types like cave air.
+    /// Returns true if the block is air.
+    ///
+    /// This only checks for normal air, not other types like cave air.
     #[inline]
     pub fn is_air(&self) -> bool {
         self == &Self::AIR
     }
 
-    /// Returns the protocol ID for the block state. IDs may change every
-    /// version, so you shouldn't hard-code them or store them in databases.
+    /// Returns the protocol ID for the block state.
+    ///
+    /// These IDs may change across Minecraft versions, so you shouldn't
+    /// hard-code them or store them in databases.
     #[inline]
     pub const fn id(&self) -> BlockStateIntegerRepr {
         self.id
@@ -71,7 +74,7 @@ impl BlockState {
 impl TryFrom<u32> for BlockState {
     type Error = ();
 
-    /// Safely converts a u32 state id to a block state.
+    /// Safely converts a u32 state ID to a block state.
     fn try_from(state_id: u32) -> Result<Self, Self::Error> {
         let state_id = state_id as BlockStateIntegerRepr;
         if Self::is_valid_state(state_id) {
@@ -84,7 +87,7 @@ impl TryFrom<u32> for BlockState {
 impl TryFrom<u16> for BlockState {
     type Error = ();
 
-    /// Safely converts a u16 state id to a block state.
+    /// Safely converts a u16 state ID to a block state.
     fn try_from(state_id: u16) -> Result<Self, Self::Error> {
         let state_id = state_id as BlockStateIntegerRepr;
         if Self::is_valid_state(state_id) {
diff --git a/azalea-block/src/fluid_state.rs b/azalea-block/src/fluid_state.rs
index cfddcc7f..80d0953b 100644
--- a/azalea-block/src/fluid_state.rs
+++ b/azalea-block/src/fluid_state.rs
@@ -112,9 +112,10 @@ impl From<BlockState> for FluidState {
     }
 }
 
-/// Sometimes Minecraft represents fluids with 0 being empty and 8 being full,
-/// and sometimes it's the opposite. You can use this function to convert
-/// in between those two representations.
+/// Convert between Minecraft's two fluid level representations.
+///
+/// This exists because sometimes Minecraft represents fluids with 0 being empty
+/// and 8 being full, and sometimes it's the opposite.
 ///
 /// You usually don't need to call this yourself, see [`FluidState`].
 pub fn to_or_from_legacy_fluid_level(level: u8) -> u8 {