add more documentation

1 files changed, 80 insertions, 7 deletions

diff --git a/src/lib.rs b/src/lib.rs
index b77f3bc..8f7d9d1 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,21 +1,58 @@
 //! `evtclib` is a crate aiming to provide utility functions to parse and work
 //! with `.evtc` reports generated by arcdps.
 //!
+//! # About evtc Files
+//!
+//! evtc files are files generated by the (inofficial) arcdps addon to Guild Wars 2. They contain
+//! metadata about a fight in the game, such as the boss's name (if it was a raid or fractal boss),
+//! the participants, and a stripped-down log of the complete fight.
+//!
+//! There are other programs (such as
+//! [GW2-Elite-Insights-Parser](https://github.com/baaron4/GW2-Elite-Insights-Parser/)) and
+//! websites (such as [dps.report](https://dps.report)) which allow you to generate reports from
+//! evtc files.
+//!
+//! A common way to store and distribute evtc files is to zip them to either a `.evtc.zip` (old
+//! way) or a `.zevtc` (new way). evtclib uses [`zip`](https://crates.io/crates/zip) to read them,
+//! prodiving the [`raw::parse_zip`][raw::parse_zip] convenience function.
+//!
+//! # Crate Structure
+//!
+//! The crate consists of two main parts: The [`raw`][raw] parser, which is used to read structured
+//! data from binary input streams, and the higher-level abstrations provided in the root and
+//! [`event`][event] submodules.
+//!
+//! Additionally, there are some defintions (such as IDs for various game items) in the
+//! [`gamedata`][gamedata] module.
+//!
+//! The main structs that you should be dealing with are the [`Log`][Log] and its components, such
+//! as [`Event`][Event] and [`Agent`][Agent].
+//!
 //! # Workflow
 //!
+//! Currently, there is no convenience function to turn a file into a [`Log`][Log] directly, so you
+//! have to use the [`raw`][raw] submodule to obtain a low-level [`Evtc`][raw::Evtc], and then
+//! convert it to the high-level [`Log`][Log].
+//!
 //! ```no_run
-//! # use std::fs::File;
-//! // Open some file for processing
-//! let mut file = File::open("my_log.evtc").unwrap();
+//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
+//! use std::fs::File;
+//! // Open a file for processing
+//! let mut file = File::open("my_log.evtc")?;
 //! // Parse the raw content of the file
-//! let raw_log = evtclib::raw::parse_file(&mut file).unwrap();
+//! let raw_log = evtclib::raw::parse_file(&mut file)?;
 //! // Process the file to do the nitty-gritty low-level stuff done
-//! let log = evtclib::process(&raw_log).unwrap();
+//! let log = evtclib::process(&raw_log)?;
 //! // Do work on the log
+//! for player in log.players() {
+//!     println!("Player {} participated!", player.account_name());
+//! }
+//! # Ok(())
+//! # }
 //! ```
 //!
-//! (Look at the note on "Buffering" in the [parser
-//! module](raw/parser/index.html#buffering))
+//! Make sure to take a look at the note on "Buffering" in the [parser
+//! module](raw/parser/index.html#buffering) in order to increase the speed of your application.
 
 use std::convert::TryFrom;
 use std::marker::PhantomData;
@@ -32,14 +69,23 @@ pub use event::{Event, EventKind};
 pub mod gamedata;
 pub use gamedata::{Boss, EliteSpec, Profession};
 
+/// Any error that can occur during the processing of evtc files.
 #[derive(Error, Debug)]
 pub enum EvtcError {
+    /// Generic error for invalid data in the evtc file.
     #[error("invalid data has been provided")]
     InvalidData,
+    /// The profession id is not known.
+    ///
+    /// The field contains the unknown profession id.
     #[error("invalid profession id: {0}")]
     InvalidProfession(u32),
+    /// The elite specialization id is not known.
+    ///
+    /// The field contains the unknown elite specialization id.
     #[error("invalid elite specialization id: {0}")]
     InvalidEliteSpec(u32),
+    /// The file contains invalid utf-8.
     #[error("utf8 decoding error: {0}")]
     Utf8Error(#[from] std::str::Utf8Error),
 }
@@ -95,12 +141,17 @@ impl Player {
 /// [Entangle](https://wiki.guildwars2.com/wiki/Entangle) or the other objects in the arena.
 #[derive(Debug, Clone, Hash, PartialEq, Eq, CopyGetters)]
 pub struct Gadget {
+    /// The id of the gadget.
+    ///
+    /// Note that gadgets do not have true ids and the id is generated "through a combination of
+    /// gadget parameters".
     #[get_copy = "pub"]
     id: u16,
     name: String,
 }
 
 impl Gadget {
+    /// The name of the gadget.
     pub fn name(&self) -> &str {
         &self.name
     }
@@ -112,12 +163,14 @@ impl Gadget {
 /// friendly characters like Mesmer's clones and illusions, Necromancer minions, and so on.
 #[derive(Debug, Clone, Hash, PartialEq, Eq, CopyGetters)]
 pub struct Character {
+    /// The id of the character.
     #[get_copy = "pub"]
     id: u16,
     name: String,
 }
 
 impl Character {
+    /// The name of the character.
     pub fn name(&self) -> &str {
         &self.name
     }
@@ -144,8 +197,17 @@ impl Character {
 /// ```
 #[derive(Debug, Clone, Hash, PartialEq, Eq)]
 pub enum AgentKind {
+    /// The agent is a player.
+    ///
+    /// The player-specific data is in the included [`Player`][Player] struct.
     Player(Player),
+    /// The agent is a gadget.
+    ///
+    /// The gadget-specific data is in the included [`Gadget`][Gadget] struct.
     Gadget(Gadget),
+    /// The agent is a character.
+    ///
+    /// The character-specific data is in the included [`Character`][Character] struct.
     Character(Character),
 }
 
@@ -753,6 +815,17 @@ impl Log {
     }
 }
 
+/// Main function to turn a low-level [`Evtc`][raw::Evtc] to a high-level [`Log`][Log].
+///
+/// This function takes an [`Evtc`][raw::Evtc] and does the required type conversions and
+/// pre-processing to get a high-level [`Log`][Log]. This pre-processing includes
+///
+/// * Setting the correct aware times for the agents
+/// * Setting the master agents for each agent
+/// * Converting all events
+///
+/// Note that the structures are quite different, so this function does not consume the given
+/// [`Evtc`][raw::Evtc].
 pub fn process(data: &raw::Evtc) -> Result<Log, EvtcError> {
     // Prepare "augmented" agents
     let mut agents = setup_agents(data)?;