From 69f8feb33465de6213963c1aadf955704bb83a08 Mon Sep 17 00:00:00 2001 From: Daniel Schadt Date: Sat, 2 May 2020 14:12:54 +0200 Subject: add more documentation --- src/raw/mod.rs | 9 +++++++++ src/raw/parser.rs | 29 +++++++++++++++++++++++++++-- src/raw/types.rs | 3 +++ 3 files changed, 39 insertions(+), 2 deletions(-) (limited to 'src/raw') diff --git a/src/raw/mod.rs b/src/raw/mod.rs index 77a8571..0b17933 100644 --- a/src/raw/mod.rs +++ b/src/raw/mod.rs @@ -33,6 +33,15 @@ pub fn parse_zip(input: R) -> ParseResult { /// at the first nul byte instead of raising an error. /// /// If the slice does not end with a nul byte, this function returns `None`. +/// +/// ``` +/// # use evtclib::raw::cstr_up_to_nul; +/// # fn doctest() -> Option<()> { +/// assert_eq!(cstr_up_to_nul(b"foo\0bar\0")?.to_bytes(), b"foo"); +/// # Some(()) +/// # } +/// # doctest().unwrap(); +/// ``` pub fn cstr_up_to_nul(bytes: &[u8]) -> Option<&CStr> { let index = bytes.iter().position(|c| *c == 0)?; CStr::from_bytes_with_nul(&bytes[..index + 1]).ok() diff --git a/src/raw/parser.rs b/src/raw/parser.rs index b7d6aad..eaf8e6b 100644 --- a/src/raw/parser.rs +++ b/src/raw/parser.rs @@ -62,6 +62,11 @@ //! buffered: cargo run --release 0.22s user 0.04s system 94% cpu 0.275 total //! raw file: cargo run --release 0.79s user 1.47s system 98% cpu 2.279 total //! ``` +//! +//! # Resources +//! +//! * [evtc readme](https://www.deltaconnected.com/arcdps/evtc/README.txt) +//! * [C++ output code](https://www.deltaconnected.com/arcdps/evtc/writeencounter.cpp) use byteorder::{LittleEndian, ReadBytesExt, LE}; use num_traits::FromPrimitive; @@ -84,9 +89,12 @@ pub struct Header { } /// A completely parsed (raw) EVTC file. +/// +/// Note that this struct does not yet do any preprocessing of the events. It is simply a +/// representation of the input file as a structured object. #[derive(Clone, Debug)] pub struct Evtc { - /// The file header values + /// The file header values. pub header: Header, /// The skill count. pub skill_count: u32, @@ -99,27 +107,44 @@ pub struct Evtc { } /// A partially-parsed EVTC file, containing everything but the events. -/// This can speed up parsing for applications which can work with the header. +/// +/// This can speed up parsing for applications which can work with the header, as the event stream +/// is the largest chunk of data that has to be parsed. #[derive(Clone, Debug)] pub struct PartialEvtc { + /// The file header values. pub header: Header, + /// The skill count. pub skill_count: u32, + /// The actual agents. pub agents: Vec, + /// The skills. pub skills: Vec, } +/// Any error that can occur during parsing. #[derive(Error, Debug)] pub enum ParseError { + /// The error stems from an underlying input/output error. #[error("IO error: {0}")] Io(#[from] io::Error), + /// The error is caused by invalid UTF-8 data in the file. + /// + /// Names in the evtc are expected to be encoded with UTF-8. #[error("utf8 decoding error: {0}")] Utf8Error(#[from] std::string::FromUtf8Error), + /// A generic error to signal invalid data has been encountered. #[error("invalid data")] InvalidData, + /// The header is malformed. + /// + /// This is the error that you get when you try to parse a non-evtc file. #[error("malformed header")] MalformedHeader, + /// The revision used by the file is not known. #[error("unknown revision: {0}")] UnknownRevision(u8), + /// The given ZIP archive is invalid. #[error("invalid archive: {0}")] InvalidZip(#[from] zip::result::ZipError), } diff --git a/src/raw/types.rs b/src/raw/types.rs index 6d72892..2e1958c 100644 --- a/src/raw/types.rs +++ b/src/raw/types.rs @@ -1,3 +1,6 @@ +//! Raw evtc structs. +//! +//! This module contains the translated definitions from arcdps's C structs. use num_derive::FromPrimitive; use std::{self, fmt}; -- cgit v1.2.3