add a bit more documentation

2 files changed, 35 insertions, 0 deletions

diff --git a/src/lib.rs b/src/lib.rs
index 0876ea3..3e1aeee 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,5 +1,21 @@
 //! `evtclib` is a crate aiming to provide utility functions to parse and work
 //! with `.evtc` reports generated by arcdps.
+//!
+//! # Workflow
+//!
+//! ```no_run
+//! # use std::fs::File;
+//! // Open some file for processing
+//! let mut file = File::open("my_log.evtc").unwrap();
+//! // Parse the raw content of the file
+//! let raw_log = evtclib::raw::parse_file(&mut file).unwrap();
+//! // Process the file to do the nitty-gritty low-level stuff done
+//! let log = evtclib::process(&raw_log).unwrap();
+//! // Do work on the log
+//! ```
+//!
+//! (Look at the note on "Buffering" in the [parser
+//! module](raw/parser/index.html#buffering))
 #![feature(try_trait)]
 #[macro_use]
 extern crate quick_error;
diff --git a/src/raw/parser.rs b/src/raw/parser.rs
index 11e892b..8e931a2 100644
--- a/src/raw/parser.rs
+++ b/src/raw/parser.rs
@@ -43,6 +43,25 @@
 //! we can use those values instead of some other garbage. The other enums
 //! already have the `None` variant, and the corresponding byte is zeroed, so
 //! there's no problem with those.
+//!
+//! # Buffering
+//!
+//! Parsing the `evtc` file does many small reads. If you supply a raw reader,
+//! each read requires a system call, and the overhead will be massive. It is
+//! advised that you wrap the readers in a `BufReader`, if the underlying reader
+//! does not do buffering on its own:
+//!
+//! ```no_run
+//! use std::io::BufReader;
+//! use std::fs::File;
+//! let mut input = BufReader::new(File::open("log.evtc").unwrap());
+//! let parsed = evtclib::raw::parse_file(&mut input);
+//! ```
+//!
+//! ```raw
+//! 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
+//! ```
 
 use byteorder::{LittleEndian, ReadBytesExt, LE};
 use num_traits::FromPrimitive;