From c36c4b74709f5b8bee8c1509576dfbac9dc47846 Mon Sep 17 00:00:00 2001 From: Joshua Goins Date: Wed, 27 Jul 2022 21:41:05 -0400 Subject: [PATCH] Document more public APIs in preparation for docs release --- src/blowfish.rs | 5 +++-- src/common.rs | 10 ++++++++++ src/dat.rs | 1 - src/equipment.rs | 14 ++++++++++++++ src/lib.rs | 27 +++++++++++++++++++++++---- src/macros.rs | 4 ++-- src/race.rs | 4 ++++ tests/integration_test.rs | 3 ++- 8 files changed, 58 insertions(+), 10 deletions(-) diff --git a/src/blowfish.rs b/src/blowfish.rs index d629df4..2718505 100755 --- a/src/blowfish.rs +++ b/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 - /// does not indicate that the wrong key was used. + /// Decrypts a block of data. If the decryption fails due to buffer overflow issues, will return + /// None - but this does not indicate that the wrong key was used. pub fn decrypt(&self, data: &[u8]) -> Option> { let padded_data = Blowfish::pad_buffer(data); diff --git a/src/common.rs b/src/common.rs index 3882179..aa1917b 100755 --- a/src/common.rs +++ b/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 => "", diff --git a/src/dat.rs b/src/dat.rs index c74ed66..6b6dfcd 100755 --- a/src/dat.rs +++ b/src/dat.rs @@ -166,7 +166,6 @@ impl DatFile { }) } - pub fn read_from_offset(&mut self, offset: u32) -> Option { let offset: u64 = (offset * 0x80) as u64; diff --git a/src/equipment.rs b/src/equipment.rs index cb8976d..b04b25e 100755 --- a/src/equipment.rs +++ b/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 { match id { 3 => Some(Slot::Head), @@ -42,6 +55,7 @@ pub fn get_slot_from_id(id: i32) -> Option { } } +/// 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, diff --git a/src/lib.rs b/src/lib.rs index d883bfc..f6b575c 100755 --- a/src/lib.rs +++ b/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. -pub mod sqpack; +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; \ No newline at end of file diff --git a/src/macros.rs b/src/macros.rs index c4a1744..041a2e9 100755 --- a/src/macros.rs +++ b/src/macros.rs @@ -1,5 +1,5 @@ -/// Creates a enum list of combined race identifiers. -#[macro_export] macro_rules! define_race_enum { +/// Creates a enum list of combined race identifiers. For example, (Hyur, Midlander, Male) becomes a new variant called HyurMidlanderMale. +#[macro_export(crate)] macro_rules! define_race_enum { ( pub enum $name:ident { $( diff --git a/src/race.rs b/src/race.rs index 98062b2..67db417 100755 --- a/src/race.rs +++ b/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, diff --git a/tests/integration_test.rs b/tests/integration_test.rs index 516f72e..aee34fa 100755 --- a/tests/integration_test.rs +++ b/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]