Merge pull request #28 from LeagueToolkit/alan/fix/docs

feat: docs + public api improvements

Author: Crauzer

crates/league-toolkit/src/core/animation/mod.rs

@@ -1,3 +1,4 @@
+//! Skeletons (rigs, joints) & animations
 pub mod joint;
 
 pub use joint::*;

crates/league-toolkit/src/core/mem/mod.rs

@@ -1,3 +1,4 @@
+//! League memory primitives (index / vertex buffers, etc)
 pub mod index_buffer;
 pub use index_buffer::*;
 pub mod vertex_buffer;

crates/league-toolkit/src/core/mesh/mod.rs

@@ -1,3 +1,4 @@
+//! Skinned & static meshes
 mod r#static;
 
 use error::ParseError;

crates/league-toolkit/src/core/meta/bin_tree/mod.rs

@@ -1,14 +1,14 @@
 use std::collections::HashMap;
 
 mod object;
-use super::error::ParseError;
 pub use object::*;
 
-pub mod read;
-pub mod write;
+mod read;
+mod write;
 
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[derive(Debug, PartialEq)]
+/// The top level tree of a bin file
 pub struct BinTree {
     pub is_override: bool,
     pub version: u32,

crates/league-toolkit/src/core/meta/bin_tree/object.rs

@@ -2,11 +2,12 @@ use std::{collections::HashMap, io};
 
 use io_ext::{measure, window};
 
-use super::{super::BinProperty, ParseError};
+use super::super::{BinProperty, Error};
 use byteorder::{ReadBytesExt, WriteBytesExt, LE};
 
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[derive(Debug, PartialEq)]
+/// A node in the bin tree
 pub struct BinTreeObject {
     pub path_hash: u32,
     pub class_hash: u32,
@@ -25,7 +26,7 @@ impl BinTreeObject {
         reader: &mut R,
         class_hash: u32,
         legacy: bool,
-    ) -> Result<Self, ParseError> {
+    ) -> Result<Self, Error> {
         let size = reader.read_u32::<LE>()?;
         let (real_size, value) = measure(reader, |reader| {
             let path_hash = reader.read_u32::<LE>()?;
@@ -37,15 +38,15 @@ impl BinTreeObject {
                 properties.insert(prop.name_hash, prop);
             }
 
-            Ok::<_, ParseError>(Self {
+            Ok::<_, Error>(Self {
                 path_hash,
                 class_hash,
                 properties,
             })
         })?;
 
         if size as u64 != real_size {
-            return Err(ParseError::InvalidSize(size as _, real_size));
+            return Err(Error::InvalidSize(size as _, real_size));
         }
         Ok(value)
     }

crates/league-toolkit/src/core/meta/bin_tree/read.rs

@@ -1,6 +1,6 @@
 use std::{collections::HashMap, io};
 
-use crate::core::meta::ParseError;
+use crate::core::meta::Error;
 
 use super::{BinTree, BinTreeObject};
 use byteorder::{ReadBytesExt, LE};
@@ -17,14 +17,14 @@ impl BinTree {
     /// * `reader` - A reader that implements io::Read and io::Seek.
     pub fn from_reader<R: io::Read + std::io::Seek + ?Sized>(
         reader: &mut R,
-    ) -> Result<Self, ParseError> {
+    ) -> Result<Self, Error> {
         let magic = reader.read_u32::<LE>()?;
         let is_override = match magic {
             Self::PROP => false,
             Self::PTCH => {
                 let override_version = reader.read_u32::<LE>()?;
                 if override_version != 1 {
-                    return Err(ParseError::InvalidFileVersion(override_version));
+                    return Err(Error::InvalidFileVersion(override_version));
                 }
 
                 // It might be possible to create an override property bin
@@ -41,17 +41,17 @@ impl BinTree {
                         Self::PTCH,
                         magic
                     );
-                    return Err(ParseError::InvalidFileSignature);
+                    return Err(Error::InvalidFileSignature);
                 }
                 true
             }
-            _ => return Err(ParseError::InvalidFileSignature),
+            _ => return Err(Error::InvalidFileSignature),
         };
 
         let version = reader.read_u32::<LE>()?;
         if !matches!(version, 1..=3) {
             // TODO (alan): distinguish override/non-override version
-            return Err(ParseError::InvalidFileVersion(version));
+            return Err(Error::InvalidFileVersion(version));
         }
 
         let dependencies = match version {
@@ -75,7 +75,7 @@ impl BinTree {
         let mut objects = HashMap::with_capacity(obj_count);
         match Self::try_read_objects(reader, &obj_classes, &mut objects, false) {
             Ok(_) => {}
-            Err(ParseError::InvalidPropertyTypePrimitive(kind)) => {
+            Err(Error::InvalidPropertyTypePrimitive(kind)) => {
                 log::warn!("Invalid prop type {kind}. Trying reading objects as legacy.");
                 Self::try_read_objects(reader, &obj_classes, &mut objects, true)?;
             }
@@ -108,7 +108,7 @@ impl BinTree {
         obj_classes: &[u32],
         objects: &mut HashMap<u32, BinTreeObject>,
         legacy: bool,
-    ) -> Result<(), ParseError> {
+    ) -> Result<(), Error> {
         objects.clear();
         for &class_hash in obj_classes {
             let tree_obj = BinTreeObject::from_reader(reader, class_hash, legacy)?;

crates/league-toolkit/src/core/meta/error.rs

@@ -3,7 +3,7 @@ use miette::Diagnostic;
 use super::property::BinPropertyKind;
 
 #[derive(Debug, thiserror::Error, Diagnostic)]
-pub enum ParseError {
+pub enum Error {
     #[error("Invalid file signature")]
     InvalidFileSignature,
     #[error("Invalid file version '{0}'")]

crates/league-toolkit/src/core/meta/mod.rs

@@ -1,10 +1,11 @@
-pub mod property;
-pub use property::BinProperty;
+//! Bin file & properties
+mod property;
+pub use property::*;
 
 mod bin_tree;
 pub use bin_tree::*;
 
-pub mod error;
+mod error;
 pub use error::*;
 
 pub mod traits;

crates/league-toolkit/src/core/meta/property/mod.rs

@@ -1,10 +1,10 @@
 use num_enum::{IntoPrimitive, TryFromPrimitive};
 use std::io;
-use value::PropertyValueEnum;
 
-use super::ParseError;
+use super::Error;
 
 pub mod value;
+pub use value::PropertyValueEnum;
 
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[derive(
@@ -45,22 +45,23 @@ pub enum BinPropertyKind {
 }
 
 impl BinPropertyKind {
+    /// Converts a u8 into a BinPropertyKind, accounting for pre/post WadChunkLink.
+    ///
     /// The WadChunkLink bin property type was newly added by Riot. For some reason they decided to put it in the middle of the enum,
     /// so we need to handle cases from before and after it existed.
     ///
     /// "Legacy" property types need to be fudged around to pretend like WadChunkLink always existed, from our pov.
     ///
     /// "Non-legacy" property types can just be used as is.
     ///
-    pub fn unpack(raw: u8, legacy: bool) -> Result<BinPropertyKind, ParseError> {
+    pub fn unpack(raw: u8, legacy: bool) -> Result<BinPropertyKind, Error> {
         use BinPropertyKind as BPK;
         if !legacy {
-            // TODO (alan): don't panic here
             return Ok(BPK::try_from_primitive(raw)?);
         }
         let mut fudged = raw;
 
-        // if the prop type comes after where WadChunkLink is now, we need to
+        // if the prop type comes after where WadChunkLink is now, we need to fudge it
         if fudged >= BPK::WadChunkLink.into() && fudged < BPK::Container.into() {
             fudged -= Into::<u8>::into(BPK::WadChunkLink);
             fudged |= Into::<u8>::into(BPK::Container);
@@ -73,6 +74,7 @@ impl BinPropertyKind {
         Ok(BinPropertyKind::try_from_primitive(fudged)?)
     }
 
+    /// Whether this property kind is a primitive type. (i8, u8, .. u32, u64, f32, Vector2, Vector3, Vector4, Matrix44, Color, String, Hash, WadChunkLink),
     pub fn is_primitive(&self) -> bool {
         use BinPropertyKind::*;
         matches!(
@@ -98,6 +100,7 @@ impl BinPropertyKind {
         )
     }
 
+    /// Whether this property kind is a container type (container, unordered container, optional, map).
     pub fn is_container(&self) -> bool {
         use BinPropertyKind::*;
         matches!(self, Container | UnorderedContainer | Optional | Map)
@@ -107,7 +110,7 @@ impl BinPropertyKind {
         self,
         reader: &mut R,
         legacy: bool,
-    ) -> Result<PropertyValueEnum, super::ParseError> {
+    ) -> Result<PropertyValueEnum, super::Error> {
         PropertyValueEnum::from_reader(reader, self, legacy)
     }
 }
@@ -122,10 +125,11 @@ pub struct BinProperty {
 
 use super::traits::PropertyValue as _;
 impl BinProperty {
+    /// Read a BinProperty from a reader. This will read the name_hash, prop kind and then value, in that order.
     pub fn from_reader<R: io::Read + std::io::Seek + ?Sized>(
         reader: &mut R,
         legacy: bool,
-    ) -> Result<Self, ParseError> {
+    ) -> Result<Self, Error> {
         use super::traits::ReaderExt;
         use byteorder::{ReadBytesExt as _, LE};
         let name_hash = reader.read_u32::<LE>()?;

crates/league-toolkit/src/core/meta/property/value/container.rs

@@ -3,7 +3,7 @@ use std::io;
 use crate::core::meta::{
     property::BinPropertyKind,
     traits::{PropertyValue as Value, ReadProperty, ReaderExt, WriteProperty, WriterExt},
-    ParseError,
+    Error,
 };
 
 use super::PropertyValueEnum;
@@ -27,10 +27,10 @@ impl ReadProperty for ContainerValue {
     fn from_reader<R: std::io::Read + std::io::Seek + ?Sized>(
         reader: &mut R,
         legacy: bool,
-    ) -> Result<Self, ParseError> {
+    ) -> Result<Self, Error> {
         let item_kind = reader.read_property_kind(legacy)?;
         if item_kind.is_container() {
-            return Err(ParseError::InvalidNesting(item_kind));
+            return Err(Error::InvalidNesting(item_kind));
         }
 
         let size = reader.read_u32::<LE>()?;
@@ -41,11 +41,11 @@ impl ReadProperty for ContainerValue {
                 let prop = PropertyValueEnum::from_reader(reader, item_kind, legacy)?;
                 items.push(prop);
             }
-            Ok::<_, ParseError>(items)
+            Ok::<_, Error>(items)
         })?;
 
         if size as u64 != real_size {
-            return Err(ParseError::InvalidSize(size as _, real_size));
+            return Err(Error::InvalidSize(size as _, real_size));
         }
 
         Ok(Self { item_kind, items })