From ed9d7936e10b8e1b5a599810b0f2f62fa6f18416 Mon Sep 17 00:00:00 2001
From: Joshua Goins <josh@redstrate.com>
Date: Sun, 14 Apr 2024 13:46:10 -0400
Subject: [PATCH] Improve the docs for model file ops and vertex declarations

---
 src/model_file_operations.rs     | 2 +-
 src/model_vertex_declarations.rs | 7 ++++++-
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/src/model_file_operations.rs b/src/model_file_operations.rs
index 16eda4c..6aaece3 100644
--- a/src/model_file_operations.rs
+++ b/src/model_file_operations.rs
@@ -7,7 +7,7 @@ use half::f16;
 use crate::ByteSpan;
 use crate::model::MDL;
 
-// Maximum value of byte, used to divide and multiply floats in that space [0.0..1.0] to [0..255]
+/// Maximum value of byte, used to divide and multiply floats in that space [0.0..1.0] to [0..255]
 const MAX_BYTE_FLOAT: f32 = u8::MAX as f32;
 
 impl MDL {
diff --git a/src/model_vertex_declarations.rs b/src/model_vertex_declarations.rs
index f334929..ad940ed 100644
--- a/src/model_vertex_declarations.rs
+++ b/src/model_vertex_declarations.rs
@@ -5,9 +5,10 @@ use std::io::SeekFrom;
 use binrw::{BinRead, BinResult, binrw, BinWrite};
 use crate::model::NUM_VERTICES;
 
-// Marker for end of stream (0xFF)
+/// Marker for end of stream (0xFF)
 const END_OF_STREAM: u8 = 0xFF;
 
+/// The format of the vertex stream.
 #[binrw]
 #[brw(repr = u8)]
 #[derive(Copy, Clone, Debug, PartialEq)]
@@ -48,6 +49,7 @@ pub enum VertexType {
     UnsignedShort4 = 17
 }
 
+/// What the vertex stream is used for.
 #[binrw]
 #[brw(repr = u8)]
 #[derive(Copy, Clone, Debug, PartialEq)]
@@ -62,6 +64,7 @@ pub enum VertexUsage {
     Color = 7,
 }
 
+/// Represents an element within a bigger vertex stream.
 #[binrw]
 #[derive(Copy, Clone, Debug, PartialEq)]
 #[allow(dead_code)]
@@ -75,6 +78,8 @@ pub struct VertexElement {
     pub usage_index: u8,
 }
 
+/// Represents the true size of VertexElement. Always use this value instead of std::mem::size_of. 
+// 3 extra bytes to account for the padding that doesn't appear in the struct itself
 pub const VERTEX_ELEMENT_SIZE: usize = std::mem::size_of::<VertexElement>() + 3;
 
 #[derive(Clone, Debug, PartialEq)]