add more documentation

3 files changed, 39 insertions, 2 deletions

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<R: Read + Seek>(input: R) -> ParseResult<Evtc> {
 /// 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<Agent>,
+    /// The skills.
     pub skills: Vec<Skill>,
 }
 
+/// 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};