Merge pull request 'WADFile Documentation' (#21) from wadfile-doc into master

Reviewed-on: https://git.batesirvintech.net/wesley/doom-oxidized/pulls/21

src/wadfile.rs

@@ -7,15 +7,33 @@ use std::{
     path::Path,
 };
 
+/// Representation of a WAD file in memory.
+///
+/// Struct is created by
+/// ```
+/// let wad_file = WADFile::from_path("WADs/doom1.wad").unwrap();
+/// ```
 pub struct WADFile {
+    /// Holds the path to the WAD file
     pub wad_path: String,
+    /// Type of WAD file (either 'IWAD' or 'PWAD')
     pub identifier: String,
+    /// Number of lumps in the WAD
     pub num_lumps: u32,
+    /// Offset to the lump directory
     pub init_offset: u32,
+    /// List of each directory entry in WAD directory
     lump_directory: Vec<Directory>,
 }
 
 impl WADFile {
+    /// Constructs a WADFile from a given path.
+    ///
+    /// Takes in a path as a string slice, then opens the file at this path.
+    /// after this it will read and parse the header file, and load the lump
+    /// directory into memory.
+    ///
+    /// TODO: Add example code here
     pub fn from_path(path: &str) -> Result<Self, &str> {
         let wad_file = Path::new(path);
 
@@ -38,22 +56,48 @@ impl WADFile {
         })
     }
 
+    /// Get a lumps name
+    ///
+    /// Gets the name of a lump given an index. Will return a
+    /// string with the lumps name.
+    ///
+    /// TODO: Add example code here
     pub fn get_lump_name(&self, index: u32) -> String {
         self.lump_directory[index as usize].lump_name.to_owned()
     }
 
+    /// Get a lumps offset
+    ///
+    /// Returns the offset where lump begins that is
+    /// identified by index.
+    ///
+    /// TODO: Add example code here
     pub fn get_lump_offset(&self, index: u32) -> u32 {
         self.lump_directory[index as usize].lump_pos.to_owned()
     }
 
+    /// Get size of a lump
+    ///
+    /// Returns the size of lump at position index.
+    ///
+    /// TODO: Add example code here
     pub fn get_lump_size(&self, index: u32) -> u32 {
         self.lump_directory[index as usize].lump_size.to_owned()
     }
 
+    /// Get length of directory list
+    ///
+    /// Returns the length of the directory list.
     pub fn get_directory_len(&self) -> usize {
         self.lump_directory.len()
     }
 
+    // Get index of a lump with given name.
+    //
+    // Will return the index of a lump that has name specified
+    // in lump_name. If not found will return None.
+    //
+    // TODO: Add example code here
     pub fn get_index_from_name(&self, lump_name: &str) -> Option<u32> {
         let mut search_lump = lump_name.to_ascii_uppercase();
 
@@ -71,6 +115,9 @@ impl WADFile {
     }
 }
 
+/// Loads lump directory into memory
+///
+/// Reads the directory in the WAD file and loads into memory.
 fn get_lump_dir(path: &str, dir_offset: &u32, num_lumps: &u32, lump_buffer: &mut Vec<Directory>) {
     let mut wad_data = File::open(&path).unwrap();
     wad_data
@@ -94,6 +141,9 @@ fn get_lump_dir(path: &str, dir_offset: &u32, num_lumps: &u32, lump_buffer: &mut
     }
 }
 
+/// Reads header data
+///
+/// Reads and returns the data from the WAD header.
 fn get_header_data(path: &str) -> (String, u32, u32) {
     let mut wad_data = File::open(&path).unwrap();