Document more public APIs in preparation for docs release

src/blowfish.rs

@@ -11,6 +11,7 @@ pub struct Blowfish {
 }
 
 impl Blowfish {
+    /// Initializes a new Blowfish session with a key.
     pub fn new(key: &[u8]) -> Blowfish {
         let mut s = Self {
             p: BLOWFISH_P,
@@ -90,8 +91,8 @@ impl Blowfish {
         vec
     }
 
-    /// Decrypts a block of data. If the decryption fails due to buffer overflow issues, will return None - but it
+    /// Decrypts a block of data. If the decryption fails due to buffer overflow issues, will return
-    /// does not indicate that the wrong key was used.
+    /// None - but this does not indicate that the wrong key was used.
     pub fn decrypt(&self, data: &[u8]) -> Option<Vec<u8>> {
         let padded_data = Blowfish::pad_buffer(data);
 

src/common.rs

@@ -3,17 +3,27 @@ use binrw::binread;
 #[binread]
 #[br(repr(u8))]
 #[repr(u8)]
+/// The language the game data is written for.
 pub enum Language {
+    /// Used for data that is language-agnostic, such as item data.
     None,
+    /// Japanese language.
     Japanese,
+    /// English language.
     English,
+    /// German language.
     German,
+    /// French language.
     French,
+    /// Chinese (Simplified) language.
     ChineseSimplified,
+    /// Chinese (Traditional) language.
     ChineseTraditional,
+    /// Korean language.
     Korean,
 }
 
+/// Returns the shorthand language code for `language`. For example, English becomes "en".
 pub fn get_language_code(lang: &Language) -> &'static str {
     match &lang {
         Language::None => "",

src/dat.rs

@@ -166,7 +166,6 @@ impl DatFile {
         })
     }
 
-
     pub fn read_from_offset(&mut self, offset: u32) -> Option<MemoryBuffer> {
         let offset: u64 = (offset * 0x80) as u64;
 

src/equipment.rs

@@ -1,18 +1,29 @@
 use crate::race::{Gender, get_race_id, Race, Subrace};
 
 #[repr(u8)]
+/// The slot the item is for.
 pub enum Slot {
+    /// The head slot. Shorthand is "met".
     Head,
+    /// The hands slot. Shorthand is "glv".
     Hands,
+    /// The legs slot. Shorthand is "dwn".
     Legs,
+    /// The feet slot. Shorthand is "sho".
     Feet,
+    /// The body or chest slot. Shorthand is "top".
     Body,
+    /// The earrings slot. Shorthand is "ear".
     Earring,
+    /// The neck slot. Shorthand is "nek".
     Neck,
+    /// The ring slot. Shorthand is "rir".
     Rings,
+    /// The wrists slot. Shorthand is "wrs".
     Wrists,
 }
 
+/// Returns the shorthand abbreviation of `slot`. For example, Body's shorthand is "top".
 pub fn get_slot_abbreviation(slot: Slot) -> &'static str {
     match slot {
         Slot::Head => "met",
@@ -27,6 +38,8 @@ pub fn get_slot_abbreviation(slot: Slot) -> &'static str {
     }
 }
 
+/// Determines the correct slot from an id. This can fail, so a None is returned when no slot matches
+/// that id.
 pub fn get_slot_from_id(id: i32) -> Option<Slot> {
     match id {
         3 => Some(Slot::Head),
@@ -42,6 +55,7 @@ pub fn get_slot_from_id(id: i32) -> Option<Slot> {
     }
 }
 
+/// Builds a game path to the equipment specified.
 pub fn build_equipment_path(model_id: i32, race: Race, subrace: Subrace, gender: Gender, slot: Slot) -> String {
     format!("chara/equipment/e{:04}/model/c{:04}e{:04}_{}.mdl",
             model_id,

src/lib.rs

@@ -1,32 +1,51 @@
 extern crate core;
 
+/// Reading and writing game data repositories, such as "ffxiv" and "ex1", and so on.
 pub mod gamedata;
 
-/// Reading game data repositories, such as "ffxiv" and "ex1", and so on.
+/// Parsing game repositories, such as "ffxiv", "ex1" and their version information.
 pub mod repository;
 
+/// Reading and writing the boot data repository.
 pub mod bootdata;
 
-/// Everything to do with reading SqPack files.
+mod sqpack;
-pub mod sqpack;
 
+/// Reading and writing SqPack index files.
 pub mod index;
-pub mod dat;
+
+mod dat;
 mod compression;
 mod model;
+
+/// All of the races in Eorzea in a nice enum package.
 pub mod race;
 
 /// Reading Excel lists (EXL).
 pub mod exl;
+
+/// Reading equipment and equipment-related data.
 pub mod equipment;
+
+/// Common structures used by other modules.
 pub mod common;
+
+/// Methods for installing game and boot patches.
 pub mod patch;
 
 #[macro_use]
 mod macros;
 
+/// Implementation of the Blowfish ECB block cipher used by the retail client.
 pub mod blowfish;
+
 mod blowfish_constants;
+
+/// Initializing a new retail game install from the official retail installer. No execution required!
 pub mod installer;
+
+/// Reading Excel header files (EXH).
 pub mod exh;
+
+/// Reading Excel data files (EXD).
 pub mod exd;

src/macros.rs

@@ -1,5 +1,5 @@
-/// Creates a enum list of combined race identifiers.
+/// Creates a enum list of combined race identifiers. For example, (Hyur, Midlander, Male) becomes a new variant called HyurMidlanderMale.
-#[macro_export] macro_rules! define_race_enum {
+#[macro_export(crate)] macro_rules! define_race_enum {
     (
 	    pub enum $name:ident {
 	        $(

src/race.rs

@@ -1,5 +1,6 @@
 #[derive(PartialEq)]
 #[repr(u8)]
+/// Gender of the character.
 pub enum Gender {
     Male,
     Female,
@@ -7,6 +8,8 @@ pub enum Gender {
 
 #[derive(PartialEq)]
 #[repr(u8)]
+/// The race's "subrace". Each race has two subraces, which are actually identical (even down to the ids!)
+/// with the exception of Hyurs, which have two unique subraces that are really two separate races.
 pub enum Subrace {
     Midlander,
     Highlander,
@@ -28,6 +31,7 @@ pub enum Subrace {
 
 #[derive(PartialEq)]
 #[repr(u8)]
+/// The major races of Eorzea.
 pub enum Race {
     Hyur,
     Elezen,

tests/integration_test.rs

@@ -1,11 +1,12 @@
 use std::env;
+use physis::index;
 
 #[test]
 #[cfg_attr(not(feature = "retail_game_testing"), ignore)]
 fn test_index_read() {
     let game_dir = env::var("FFXIV_GAME_DIR").unwrap();
 
-    physis::index::IndexFile::from_existing(format!("{}/game/sqpack/ffxiv/000000.win32.index", game_dir).as_str());
+    index::IndexFile::from_existing(format!("{}/game/sqpack/ffxiv/000000.win32.index", game_dir).as_str());
 }
 
 #[test]