Add documentation comments for all items

src/resource/biomes.rs

@@ -1,25 +1,51 @@
+//! Biome data structures
+
 use serde::{Deserialize, Serialize};
 
 use super::Color;
 
+/// Grass color modifier used by a biome
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub enum BiomeGrassColorModifier {
+	/// Grass color modifier used by the dark forest biome
 	DarkForest,
+	/// Grass color modifier used by swamp biomes
 	Swamp,
 }
 
+/// A biome specification
+///
+/// A Biome contains all information about a biome necessary to compute a block
+/// color given a block type and depth
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct Biome {
+	/// Temperature value
+	///
+	/// For more efficient storage, the temperature is stored as an integer
+	/// after mutiplying the raw value by 20
 	pub temp: i8,
+	/// Downfall value
+	///
+	/// For more efficient storage, the downfall is stored as an integer
+	/// after mutiplying the raw value by 20
 	pub downfall: i8,
+	/// Water color override
 	pub water_color: Option<Color>,
+	/// Foliage color override
 	pub foliage_color: Option<Color>,
+	/// Grass color override
 	pub grass_color: Option<Color>,
+	/// Grass color modifier
 	pub grass_color_modifier: Option<BiomeGrassColorModifier>,
 }
 
 impl Biome {
+	/// Constructs a new Biome
 	const fn new(temp: i16, downfall: i16) -> Biome {
+		/// Helper to encode temperature and downfall values
+		///
+		/// Converts temperatue and downfall from the input format
+		/// (mutiplied by 100) to i8 range for more efficient storage.
 		const fn encode(v: i16) -> i8 {
 			(v / 5) as i8
 		}
@@ -33,6 +59,7 @@ impl Biome {
 		}
 	}
 
+	/// Builder function to override the biome water color
 	const fn water(self, water_color: [u8; 3]) -> Biome {
 		Biome {
 			water_color: Some(Color(water_color)),
@@ -40,6 +67,7 @@ impl Biome {
 		}
 	}
 
+	/// Builder function to override the biome foliage color
 	const fn foliage(self, foliage_color: [u8; 3]) -> Biome {
 		Biome {
 			foliage_color: Some(Color(foliage_color)),
@@ -47,6 +75,7 @@ impl Biome {
 		}
 	}
 
+	/// Builder function to override the biome grass color
 	const fn grass(self, grass_color: [u8; 3]) -> Biome {
 		Biome {
 			grass_color: Some(Color(grass_color)),
@@ -54,6 +83,7 @@ impl Biome {
 		}
 	}
 
+	/// Builder function to set a grass color modifier
 	const fn modify(self, grass_color_modifier: BiomeGrassColorModifier) -> Biome {
 		Biome {
 			grass_color_modifier: Some(grass_color_modifier),
@@ -61,25 +91,34 @@ impl Biome {
 		}
 	}
 
+	/// Decodes a temperature or downfall value from the storage format to
+	/// f32 for further calculation
 	fn decode(val: i8) -> f32 {
 		f32::from(val) / 20.0
 	}
 
+	/// Returns the biome's temperature decoded to its original float value
 	pub fn temp(&self) -> f32 {
 		Self::decode(self.temp)
 	}
 
+	/// Returns the biome's downfall decoded to its original float value
 	pub fn downfall(&self) -> f32 {
 		Self::decode(self.downfall)
 	}
 }
 
-// Data extracted from Minecraft code decompiled using https://github.com/Hexeption/MCP-Reborn
-
-#[allow(clippy::zero_prefixed_literal)]
+/// Standard biome specifications
 pub const BIOMES: &[(&str, Biome)] = {
 	use BiomeGrassColorModifier::*;
 
+	// Data extracted from Minecraft code decompiled using https://github.com/Hexeption/MCP-Reborn
+
+	// We can't use floats in const functions, to temperature and downfall values
+	// are specified multipled by 100. The underscore is used in place of the decimal point
+	// of the original values.
+
+	#[allow(clippy::zero_prefixed_literal)]
 	&[
 		// Overworld
 		(
@@ -189,6 +228,10 @@ pub const BIOMES: &[(&str, Biome)] = {
 	]
 };
 
+/// Biome ID aliases
+///
+/// Some biomes have been renamed or merged in recent Minecraft versions.
+/// Maintain a list of aliases to support chunks saved by older versions.
 pub const BIOME_ALIASES: &[(&str, &str)] = &[
 	// Biomes fix
 	("beaches", "beach"),
@@ -292,6 +335,7 @@ pub const BIOME_ALIASES: &[(&str, &str)] = &[
 	("deep_warm_ocean", "warm_ocean"),
 ];
 
+/// Maps old numeric biome IDs to new string IDs
 pub fn legacy_biome(index: u8) -> &'static str {
 	match index {
 		0 => "ocean",

src/resource/block_color.rs

@@ -1,15 +1,23 @@
+//! Functions for computations of block colors
+
 use super::{Biome, BlockType, Color};
 
 use glam::Vec3;
 
+/// Converts an u8 RGB color to a float vector
 fn color_vec_unscaled(color: Color) -> Vec3 {
 	Vec3::from_array(color.0.map(f32::from))
 }
 
+/// Converts an u8 RGB color to a float vector, scaling the components to 0.0..1.0
 fn color_vec(color: Color) -> Vec3 {
 	color_vec_unscaled(color) / 255.0
 }
 
+/// Helper for grass and foliage colors
+///
+/// Biome temperature and downfall are modified based on the depth value
+/// before using them to compute the final color
 fn color_from_params(colors: &[Vec3; 3], biome: &Biome, depth: f32) -> Vec3 {
 	let temp = (biome.temp() - f32::max((depth - 64.0) / 600.0, 0.0)).clamp(0.0, 1.0);
 	let downfall = biome.downfall().clamp(0.0, 1.0) * temp;
@@ -17,9 +25,13 @@ fn color_from_params(colors: &[Vec3; 3], biome: &Biome, depth: f32) -> Vec3 {
 	colors[0] + temp * colors[1] + downfall * colors[2]
 }
 
+/// Extension trait with helpers for computing biome-specific block colors
 trait BiomeExt {
+	/// Returns the grass color of the biome at a given depth
 	fn grass_color(&self, depth: f32) -> Vec3;
+	/// Returns the foliage color of the biome at a given depth
 	fn foliage_color(&self, depth: f32) -> Vec3;
+	/// Returns the water color of the biome
 	fn water_color(&self) -> Vec3;
 }
 
@@ -27,12 +39,15 @@ impl BiomeExt for Biome {
 	fn grass_color(&self, depth: f32) -> Vec3 {
 		use super::BiomeGrassColorModifier::*;
 
+		/// Color matrix extracted from grass color texture
 		const GRASS_COLORS: [Vec3; 3] = [
 			Vec3::new(0.502, 0.706, 0.592),   // lower right
 			Vec3::new(0.247, 0.012, -0.259),  // lower left - lower right
 			Vec3::new(-0.471, 0.086, -0.133), // upper left - lower left
 		];
+		/// Used for dark forst grass color modifier
 		const DARK_FOREST_GRASS_COLOR: Vec3 = Vec3::new(0.157, 0.204, 0.039); // == color_vec(Color([40, 52, 10]))
+		/// Grass color in swamp biomes
 		const SWAMP_GRASS_COLOR: Vec3 = Vec3::new(0.416, 0.439, 0.224); // == color_vec(Color([106, 112, 57]))
 
 		let regular_color = || {
@@ -49,6 +64,7 @@ impl BiomeExt for Biome {
 	}
 
 	fn foliage_color(&self, depth: f32) -> Vec3 {
+		/// Color matrix extracted from foliage color texture
 		const FOLIAGE_COLORS: [Vec3; 3] = [
 			Vec3::new(0.376, 0.631, 0.482),   // lower right
 			Vec3::new(0.306, 0.012, -0.317),  // lower left - lower right
@@ -61,6 +77,9 @@ impl BiomeExt for Biome {
 	}
 
 	fn water_color(&self) -> Vec3 {
+		/// Default biome water color
+		///
+		/// Used for biomes that don't explicitly set a water color
 		const DEFAULT_WATER_COLOR: Vec3 = Vec3::new(0.247, 0.463, 0.894); // == color_vec(Color([63, 118, 228]))
 
 		self.water_color
@@ -69,15 +88,22 @@ impl BiomeExt for Biome {
 	}
 }
 
+/// Color multiplier for birch leaves
 const BIRCH_COLOR: Vec3 = Vec3::new(0.502, 0.655, 0.333); // == color_vec(Color([128, 167, 85]))
+/// Color multiplier for spruce leaves
 const EVERGREEN_COLOR: Vec3 = Vec3::new(0.380, 0.600, 0.380); // == color_vec(Color([97, 153, 97]))
 
+/// Determined if calling [block_color] for a given [BlockType] needs biome information
 pub fn needs_biome(block: BlockType) -> bool {
 	use super::BlockFlag::*;
 
 	block.is(Grass) || block.is(Foliage) || block.is(Water)
 }
 
+/// Determined the block color to display for a given [BlockType]
+///
+/// [needs_biome] must be used to determine whether passing a [Biome] is necessary.
+/// Will panic if a [Biome] is necessary, but none is passed.
 pub fn block_color(block: BlockType, biome: Option<&Biome>, depth: f32) -> Vec3 {
 	use super::BlockFlag::*;
 

src/resource/legacy_block_types.rs

@@ -1,12 +1,18 @@
+//! Mapping of old numeric block type and damage/subtype IDs to new string IDs
+
+/// Helper for block types that don't use the damage/subtype data
 const fn simple(id: &str) -> [&str; 16] {
 	[
 		id, id, id, id, id, id, id, id, id, id, id, id, id, id, id, id,
 	]
 }
 
+/// Default block type for unassigned numeric IDs
 const DEF: &str = "air";
+/// Default entry for block type numbers that are unassigned regardless of subtype
 const EMPTY: [&str; 16] = simple(DEF);
 
+/// Mapping from each numeric block type and damage/subtype ID to new string ID
 pub const LEGACY_BLOCK_TYPES: [[&str; 16]; 256] = [
 	/* 0 */
 	simple("air"),

src/resource/mod.rs

@@ -1,43 +1,62 @@
+//! Data describing Minecraft biomes and block types
+
 mod biomes;
 mod block_color;
-mod block_types;
 mod legacy_block_types;
 
+#[allow(clippy::missing_docs_in_private_items)] // Generated module
+mod block_types;
+
 use std::collections::HashMap;
 
 use enumflags2::{bitflags, BitFlags};
 use serde::{Deserialize, Serialize};
 
+/// Flags describing special properties of [BlockType]s
 #[bitflags]
 #[repr(u8)]
 #[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
 pub enum BlockFlag {
+	/// The block type is opaque
 	Opaque,
+	/// The block type is colored using biome grass colors
 	Grass,
+	/// The block type is colored using biome foliage colors
 	Foliage,
+	/// The block type is birch foliage
 	Birch,
+	/// The block type is spurce foliage
 	Spruce,
+	/// The block type is colored using biome water colors
 	Water,
 }
 
+/// An RGB color
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct Color(pub [u8; 3]);
 
+/// A block type specification
 #[derive(Debug, Clone, Copy, Serialize, Deserialize)]
 pub struct BlockType {
+	/// Bit set of [BlockFlag]s describing special properties of the block type
 	pub flags: BitFlags<BlockFlag>,
+	/// Base color of the block type
 	pub color: Color,
 }
 
 impl BlockType {
+	/// Checks whether a block type has a given [BlockFlag] set
 	pub fn is(&self, flag: BlockFlag) -> bool {
 		self.flags.contains(flag)
 	}
 }
 
+/// Used to look up standard Minecraft block types
 #[derive(Debug)]
 pub struct BlockTypes {
+	/// Map of string IDs to block types
 	block_type_map: HashMap<String, BlockType>,
+	/// Array used to look up old numeric block type and subtype values
 	legacy_block_types: Box<[[BlockType; 16]; 256]>,
 }
 
@@ -59,12 +78,14 @@ impl Default for BlockTypes {
 }
 
 impl BlockTypes {
+	/// Resolves a Minecraft 1.13+ string block type ID
 	#[inline]
 	pub fn get(&self, id: &str) -> Option<BlockType> {
 		let suffix = id.strip_prefix("minecraft:")?;
 		self.block_type_map.get(suffix).copied()
 	}
 
+	/// Resolves a Minecraft pre-1.13 numeric block type ID
 	#[inline]
 	pub fn get_legacy(&self, id: u8, data: u8) -> Option<BlockType> {
 		Some(self.legacy_block_types[id as usize][data as usize])
@@ -74,9 +95,12 @@ impl BlockTypes {
 pub use biomes::{Biome, BiomeGrassColorModifier};
 pub use block_color::{block_color, needs_biome};
 
+/// Used to look up standard Minecraft biome types
 #[derive(Debug)]
 pub struct BiomeTypes {
+	/// Map of string IDs to biome types
 	biome_map: HashMap<String, &'static Biome>,
+	/// Array used to look up old numeric biome IDs
 	legacy_biomes: Box<[&'static Biome; 256]>,
 }
 
@@ -112,12 +136,14 @@ impl Default for BiomeTypes {
 }
 
 impl BiomeTypes {
+	/// Resolves a Minecraft 1.18+ string biome type ID
 	#[inline]
 	pub fn get(&self, id: &str) -> Option<&Biome> {
 		let suffix = id.strip_prefix("minecraft:")?;
 		self.biome_map.get(suffix).copied()
 	}
 
+	/// Resolves a Minecraft pre-1.18 numeric biome type ID
 	#[inline]
 	pub fn get_legacy(&self, id: u8) -> Option<&Biome> {
 		Some(self.legacy_biomes[id as usize])