docs: Add crate documentation (#21)

This (hopefully 🤞) adds all of the necessary documentation. Closes #2.

Author: ev3nvy

src/entries.rs

@@ -1,3 +1,9 @@
+//! Collection of entries from the parsed flatbuffer schema.
+//!
+//! NOTE: these structs are only useful for viewing the internal structure of the parsed
+//! flatbuffer schema. If you just wish to see the containing files and download them, see
+//! [File][crate::File].
+
 mod bundle_entry;
 mod chunk_entry;
 mod directory_entry;

src/entries/bundle_entry.rs

@@ -2,10 +2,18 @@ use crate::generated::rman::Bundle;
 
 use super::chunk_entry::ChunkEntry;
 
+/// Single bundle entry object.
+///
+/// This is identical to the schema in [rman-schema][rman-schema] and exists to provide a
+/// persistent structure for the BundleEntry.
+///
+/// [rman-schema]: https://github.com/ev3nvy/rman-schema
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[derive(Debug, Default, Clone, PartialEq, Eq)]
 pub struct BundleEntry {
+    /// Id of the bundle entry.
     pub id: u64,
+    /// A vector of chunk entries.
     pub chunks: Vec<ChunkEntry>,
 }
 

src/entries/chunk_entry.rs

@@ -1,10 +1,23 @@
 use crate::generated::rman::Chunk;
 
+/// Single chunk entry object.
+///
+/// This is identical to the schema in [rman-schema][rman-schema] and exists to provide a
+/// persistent structure for the ChunkEntry.
+///
+/// [rman-schema]: https://github.com/ev3nvy/rman-schema
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[derive(Debug, Default, Clone, PartialEq, Eq)]
 pub struct ChunkEntry {
+    /// Id of the chunk entry.
     pub id: u64,
+    /// Chunk size before decompression.
+    ///
+    /// Mainly used when downloading files.
     pub compressed_size: u32,
+    /// Chunk size after decompression.
+    ///
+    /// Mainly used when downloading files.
     pub uncompressed_size: u32,
 }
 

src/entries/directory_entry.rs

@@ -1,10 +1,22 @@
 use crate::generated::rman::Directory;
 
+/// Single directory entry object.
+///
+/// This is identical to the schema in [rman-schema][rman-schema] and exists to provide a
+/// persistent structure for the DirectoryEntry.
+///
+/// [rman-schema]: https://github.com/ev3nvy/rman-schema
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[derive(Debug, Default, Clone, PartialEq, Eq)]
 pub struct DirectoryEntry {
+    /// Id of the directory entry.
     pub id: u64,
+    /// Id of the parent directory entry.
+    ///
+    /// NOTE: root directory (which is tipically the first DirectoryEntry in the vector) typically
+    /// has an `id` of 0, yet still has a `parent_id` of 0.
     pub parent_id: u64,
+    /// Name of the directory entry.
     pub name: String,
 }
 

src/entries/file_entry.rs

@@ -1,20 +1,41 @@
 use crate::generated::rman::File;
 
+/// Single file entry object.
+///
+/// This is identical to the schema in [rman-schema][rman-schema] and exists to provide a
+/// persistent structure for the FileEntry.
+///
+/// [rman-schema]: https://github.com/ev3nvy/rman-schema
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[derive(Debug, Default, Clone, PartialEq, Eq)]
 pub struct FileEntry {
+    /// Id of the file entry.
     pub id: u64,
+    /// Id of the directory entry, to which it belongs.
     pub directory_id: u64,
+    /// Size of the file entry in bytes.
     pub size: u32,
+    /// Name of the file entry.
     pub name: String,
+    /// Applicable languages, stored as a bit mask.
     pub language_mask: u64,
+    /// Field with an unknown function and type (it might also be an [`i8`]).
     pub unk5: u8,
+    /// Field with an unknown function and type (it might also be an [`i8`]).
     pub unk6: u8,
+    /// A vector of [chunk ids](crate::entries::ChunkEntry::id) that make up the file.
     pub chunk_ids: Vec<u64>,
+    /// Field with an unknown function and type (it might also be an [`i8`]).
+    ///
+    /// NOTE: seems to always be 1 when a part of `.app` file on macOS.
     pub unk8: u8,
+    /// Symbolic link of the file entry.
     pub symlink: String,
+    /// Field with an unknown function and type (it might also be an [`i16`]).
     pub unk10: u16,
+    /// Id of the param entry, which provides info about content-defined chunking.
     pub param_id: u8,
+    /// Permissions for the given file entry.
     pub permissions: u8,
 }
 

src/entries/key_entry.rs

@@ -1,9 +1,17 @@
 use crate::generated::rman::Key;
 
+/// Single key entry object.
+///
+/// This is identical to the schema in [rman-schema][rman-schema] and exists to provide a
+/// persistent structure for the KeyEntry.
+///
+/// [rman-schema]: https://github.com/ev3nvy/rman-schema
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[derive(Debug, Default, Clone, PartialEq, Eq)]
 pub struct KeyEntry {
+    /// Field with an unknown function and type (it might also be an [`i16`]).
     pub unk0: u16,
+    /// Field with an unknown function and type (it might also be an [`i32`]).
     pub unk1: u32,
 }
 

src/entries/language_entry.rs

@@ -1,9 +1,28 @@
 use crate::generated::rman::Language;
 
+/// Single language entry object.
+///
+/// This is identical to the schema in [rman-schema][rman-schema] and exists to provide a
+/// persistent structure for the LanguageEntry.
+///
+/// [rman-schema]: https://github.com/ev3nvy/rman-schema
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[derive(Debug, Default, Clone, PartialEq, Eq)]
 pub struct LanguageEntry {
+    /// Id of the language entry.
     pub id: u8,
+    /// Name of the language in the language-region variant of the [RFC 5646 standard][rfc-5646],
+    /// however, underscores are used instead of hyphens.
+    ///
+    /// There are also non languages present.
+    /// A non-exhaustive list of values that are not languagues:
+    /// - `krrating`
+    /// - `mature`
+    /// - `twmlogo`
+    /// - `vnglogo`
+    /// - `all_loc`
+    ///
+    /// [rfc-5646]: https://www.rfc-editor.org/rfc/rfc5646.html
     pub name: String,
 }
 

src/entries/param_entry.rs

@@ -1,12 +1,50 @@
 use crate::generated::rman::Param;
 
+/// Single param entry object.
+///
+/// This is identical to the schema in [rman-schema][rman-schema] and exists to provide a
+/// persistent structure for the ParamEntry.
+///
+/// [rman-schema]: https://github.com/ev3nvy/rman-schema
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[derive(Debug, Default, Clone, PartialEq, Eq)]
 pub struct ParamEntry {
+    /// Field with an unknown function and type (it might also be an [`i16`]).
     pub unk0: u16,
+    /// Determines the hash type used when generating chunks.
+    ///
+    /// - 0 - Invalid/None
+    /// - 1 - SHA256
+    /// - 2 - SHA512
+    /// - 3 - RIOT_HKDF
+    ///
+    /// These values are copied straight from
+    /// [moonshadow565's implementation][moonshadow565-rman-rchunk].
+    /// More about hashing on their [official blog][manifest].
+    ///
+    /// [moonshadow565-rman-rchunk]: https://github.com/moonshadow565/rman/blob/master/lib/rlib/rchunk.hpp
+    /// [manifest]: https://technology.riotgames.com/news/supercharging-data-delivery-new-league-patcher
     pub chunking_version: u8,
+    /// Minimum chunk size.
+    ///
+    /// For more info on what this does, see [Riot's blog][manifest] or [FastCDC pdf][fast-cdc].
+    ///
+    /// [manifest]: https://technology.riotgames.com/news/supercharging-data-delivery-new-league-patcher
+    /// [fast-cdc]: https://www.usenix.org/system/files/conference/atc16/atc16-paper-xia.pdf
     pub min_chunk_size: u32,
+    /// Chunk size.
+    ///
+    /// For more info on what this does, see [Riot's blog][manifest] or [FastCDC pdf][fast-cdc].
+    ///
+    /// [manifest]: https://technology.riotgames.com/news/supercharging-data-delivery-new-league-patcher
+    /// [fast-cdc]: https://www.usenix.org/system/files/conference/atc16/atc16-paper-xia.pdf
     pub chunk_size: u32,
+    /// Maximum chunk size.
+    ///
+    /// For more info on what this does, see [Riot's blog][manifest] or [FastCDC pdf][fast-cdc].
+    ///
+    /// [manifest]: https://technology.riotgames.com/news/supercharging-data-delivery-new-league-patcher
+    /// [fast-cdc]: https://www.usenix.org/system/files/conference/atc16/atc16-paper-xia.pdf
     pub max_chunk_size: u32,
 }
 

src/error.rs

@@ -1,31 +1,99 @@
 use thiserror::Error;
 
+/// Alias for a [`Result`][core::result::Result] with the error type [`ManifestError`].
 pub type Result<T> = core::result::Result<T, ManifestError>;
 
+/// This enum represents all possible errors that may occur when parsing a file.
 #[derive(Error, Debug)]
 pub enum ManifestError {
+    /// The error was caused by a failure to seek to a desired offset.
+    ///
+    /// This error occurs when [`Seek`][std::io::Seek] fails.
     #[error("Could not seek to desired position. Error: {0}")]
     SeekError(std::io::Error),
+    /// The error was caused by invalid magic bytes.
+    ///
+    /// This error occurs when the first four bytes (magic bytes) do not equal `0x52`, `0x4D`,
+    /// `0x41` and `0x4E` (or `R`, `M`, `A`, `N` in ascii) respectively.
+    ///
+    /// Usually caused by providing a file that is not a Riot Manifest file.
     #[error("Invalid magic bytes (expected: \"0x4E414D52\", was: \"{0:#010x}\").")]
     InvalidMagicBytes(u32),
+    /// The error was caused by invalid major version.
+    ///
+    /// This error occurs when the major version in the file header doesn't equal 2.
+    ///
+    /// Should only occur if the manifest format gets a major change or an update, Parser
+    /// may no longer function if this happens.
+    ///
+    /// NOTE: The feature `version_error` must be enabled for this error to occur.
     #[error("Unsupported major version (expected: \"2\", was: \"{0}\").")]
     #[cfg(feature = "version_error")]
     InvalidMajor(u8),
+    /// The error was caused by invalid minor version.
+    ///
+    /// This error occurs when the minor version in the file header doesn't equal 0.
+    ///
+    /// Should only occur if the manifest format gets a minor change or an update. Parser
+    /// should still be functional if this happens,
+    ///
+    /// NOTE: The feature `version_error` must be enabled for this error to occur.
     #[error("Unsupported minor version (expected: \"0\", was: \"{0}\").")]
     #[cfg(feature = "version_error")]
     InvalidMinor(u8),
+    /// The error was caused by an invalid offset.
+    ///
+    /// This error occurs when the offset is smaller or larger than the file itself.
+    ///
+    /// Should never happen for official, Riot-made manifests.
     #[error("Offset ({0}) is larger than the total file size.")]
     InvalidOffset(u32),
+    /// The error was caused by compressed size being too large.
+    ///
+    /// This error occurs when the compressed size is larger than the file itself.
+    ///
+    /// Should never happen for official, Riot-made manifests.
     #[error("Compressed size ({0}) is larger than the total file size.")]
     CompressedSizeTooLarge(u32),
+    /// The error was caused by a failure to read or write bytes on an IO stream.
+    ///
+    /// This error occurs when [`read_exact`][std::io::Read::read_exact], any `read_` method in
+    /// [`byteorder::ReadBytesExt`], or [`File::open`][std::fs::File::open] fails.
+    ///
+    /// Usually caused by invalid or inaccessible path or unexpected eof when parsing a header.
     #[error("{0}")]
     IoError(#[from] std::io::Error),
+    /// The error was caused by a failure to convert from one number type to another.
+    ///
+    /// This error occurs when the conversion from or into [`usize`] fails.
+    ///
+    /// Should never fail on 32-bit (or higher) targets.
     #[error("Conversion failed. Error: {0}")]
     ConversionFailure(#[from] std::num::TryFromIntError),
+    /// The error was caused by a failure to decompress zstd data.
+    ///
+    /// This error occurs when [`decompress`][zstd::bulk::decompress] fails.
+    ///
+    /// Should never happen for official, Riot-made manifests.
     #[error("{0}")]
     ZstdDecompressError(std::io::Error),
+    /// The error was caused by a failure to parse [`FileEntry`][crate::entries::FileEntry] into
+    /// [`File`][crate::File].
+    ///
+    /// This error occurs when either a [`directory_id`](crate::entries::FileEntry::directory_id)
+    /// or [`parent_id`](crate::entries::DirectoryEntry::parent_id) points to an invalid
+    /// [`DirectoryEntry`][crate::entries::DirectoryEntry] or when
+    /// [`chunk_id`](crate::entries::FileEntry::chunk_ids) refers to an invalid
+    /// [`ChunkEntry`][crate::entries::ChunkEntry].
+    ///
+    /// Should never happen for official, Riot-made manifests.
     #[error("{0}")]
     FileParseError(String),
+    /// The error was caused by an invalid flatbuffer.
+    ///
+    /// This error occurs when a flatbuffer fails to verify.
+    ///
+    /// Should never happen for official, Riot-made manifests.
     #[error("{0}")]
     FlatbufferError(#[from] flatbuffers::InvalidFlatbuffer),
 }

src/file.rs

@@ -3,21 +3,65 @@ use std::collections::HashMap;
 use crate::entries::FileEntry;
 use crate::{ManifestError, Result};
 
+/// Single file object.
+///
+/// Represents a file and it's properties that can be downloaded and written to a file system.
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[derive(Debug, Default, Clone, PartialEq, Eq)]
 pub struct File {
+    /// Id of the file.
     pub id: u64,
+    /// File name.
     pub name: String,
+    /// Permissions for the given file.
     pub permissions: u8,
+    /// Size of the file entry in bytes.
     pub size: u32,
+    /// Absolute path to the file, where root is one of the
+    /// [directory entries][crate::entries::DirectoryEntry].
     pub path: String,
+    /// Symbolic link of the file.
     pub symlink: String,
+    /// A vector of applicable languages.
     pub languages: Vec<String>,
     #[allow(dead_code)]
     chunks: Vec<(u64, u64, u32, u32)>,
 }
 
 impl File {
+    /// Parses [`FileEntry`] into a [`File`] object.
+    ///
+    /// First parameter is a [`FileEntry`] that is parsed into a [`File`], the other three are
+    /// [`HashMap`]s used for fast lookups for the required data.
+    ///
+    /// Here is how they are structured:
+    /// - Parameter `language_entries` is a [`HashMap`] where the key is a
+    /// [language id](crate::entries::LanguageEntry::id) and the value is a
+    /// [language name](crate::entries::LanguageEntry::name).
+    ///
+    /// - Parameter `directories` is a [`HashMap`] where the key is a
+    /// [directory id](crate::entries::DirectoryEntry::id) and the value is a tuple of:
+    ///   - [directory name](crate::entries::DirectoryEntry::name)
+    ///   - and [parent directory id](crate::entries::DirectoryEntry::parent_id).
+    ///
+    /// - Parameter `chunk_entries` is a [`HashMap`] where the key is a
+    /// [chunk id](crate::entries::ChunkEntry::id) and the value is a tuple of:
+    ///   - [bundle id](crate::entries::BundleEntry::id),
+    ///   - offset in bundle (to this specific chunk),
+    ///   - [uncompressed size](crate::entries::ChunkEntry::uncompressed_size)
+    ///   - and [compressed size](crate::entries::ChunkEntry::compressed_size).
+    ///
+    /// [`File`]: crate::File
+    /// [`FileEntry`]: crate::entries::FileEntry
+    ///
+    /// # Errors
+    ///
+    /// If a directory with [provided id](crate::entries::FileEntry::directory_id) or
+    /// [parent id](crate::entries::DirectoryEntry::parent_id) does not exist within the
+    /// `directories` [`HashMap`], or if a chunk with
+    /// [chunk id](crate::entries::FileEntry::chunk_ids) does not exist within the `chunk_entries`
+    /// [`HashMap`], the error [`FileParseError`][crate::ManifestError::FileParseError] is
+    /// returned.
     pub fn parse(
         file: &FileEntry,
         language_entries: &HashMap<u8, String>,
@@ -83,6 +127,9 @@ impl File {
 }
 
 impl File {
+    /// Function to download the associated file contents.
+    ///
+    /// Currently unimplemented.
     pub fn download(&self) {
         unimplemented!("downloading not yet implemented");
     }

src/lib.rs

@@ -1,7 +1,105 @@
-// #![deny(missing_docs)]
+#![deny(missing_docs)]
 #![deny(missing_debug_implementations)]
 #![deny(clippy::all, clippy::unwrap_used)]
 
+//! # rman
+//!
+//! The `rman` crate provides a convenient api for parsing and downloading
+//! [manifest files][manifest]. This format is specific to games made by [Riot Games][riot-games].
+//!
+//! Crates name is derived from the 4 magic bytes at the beginning of the `.manifest` file,
+//! which correspond to `R`, `M`, `A`, `N` ascii characters. `RMAN` probably stands for
+//! Riot Manifest (or a variation of the two words).
+//!
+//! # Usage
+//!
+//! This crate is on [crates.io][rman-crates-io]. To use it, just add the dependency `rman` to the
+//! `Cargo.toml` file.
+//!
+//! ```toml
+//! [dependencies]
+//! rman = "0.1"
+//! ```
+//!
+//! # Example: parsing a manifest file from path
+//!
+//! Easiest way to parse a manifest file is to just provide a path to it's location.
+//!
+//! [`from_path`][crate::RiotManifest::from_path] calls [`File::open`][std::fs::File::open]
+//! internally, so everything from [`&str`][str] to [`PathBuf`][std::path::PathBuf] is a valid
+//! argument.
+//!
+//! ```
+//! use rman::RiotManifest;
+//!
+//! let path = "file.manifest";
+//! # let path = concat!(env!("OUT_DIR"), "/valid.manifest");
+//!
+//! let manifest = RiotManifest::from_path(path).unwrap();
+//!
+//! assert_eq!(manifest.data.files.len(), 1);
+//! ```
+//!
+//! # Example: parsing a manifest file from reader
+//!
+//! If you read the file from another source, or you already have the file in a reader,
+//! you can instead call [`from_reader`](crate::RiotManifest::from_reader) to parse the file.
+//!
+//! Internally, this is what [`from_path`](crate::RiotManifest::from_path) calls, so the response
+//! of the two functions should be identical.
+//!
+//! ```
+//! use std::fs;
+//! use std::io::BufReader;
+//!
+//! use rman::RiotManifest;
+//!
+//! let path = "file.manifest";
+//! # let path = concat!(env!("OUT_DIR"), "/valid.manifest");
+//! let file = fs::File::open(path).unwrap();
+//! let mut reader = BufReader::new(file);
+//!
+//! let manifest = RiotManifest::from_reader(&mut reader).unwrap();
+//!
+//! assert_eq!(manifest.data.files.len(), 1);
+//! ```
+//!
+//! # Scope
+//!
+//! This crate:
+//! - reads the `.manifest` file, and verifies it's a valid `rman` file,
+//! - decompresses the containing data which was compressed using [zstd][zstd],
+//! - parses the decompressed [FlatBuffer][flatbuffers] data,
+//! - stores all of the parsed data on [`ManifestData`][crate::ManifestData],
+//! - combines the data into a vector of downloadable [`File`][crate::File]s,
+//! - provides a function to [`download`][crate::File::download] specific files.
+//!
+//! This crate doesn't:
+//! - generate a `.manifest` file,
+//! - create or parse chunks.
+//!
+//! # Feature: `default`
+//!
+//! By default, all of the features are disabled.
+//!
+//! # Feature: `version_error`
+//!
+//! If enabled, throws errors on unknown manifest versions, instead of continuing and assuming it
+//! works.
+//!
+//! # Feature: `serde`
+//!
+//! If enabled, all structs in [`entries`][crate::entries], as well as [`File`][crate::File]
+//! will implement [`Serialize`][serde-serialize] and [`Deserialize`][serde-deserialize].
+//!
+//! [flatbuffers]: https://github.com/google/flatbuffers
+//! [manifest]: https://technology.riotgames.com/news/supercharging-data-delivery-new-league-patcher
+//! [riot-games]: https://www.riotgames.com
+//! [rman-crates-io]: https://crates.io/crates/rman
+//! [serde-serialize]: https://docs.rs/serde/latest/serde/trait.Serialize.html
+//! [serde-deserialize]: https://docs.rs/serde/latest/serde/trait.Deserialize.html
+//! [zstd]: https://github.com/facebook/zstd
+
 pub mod entries;
 mod error;
 mod file;

src/parser.rs

@@ -12,13 +12,43 @@ use log::debug;
 
 use crate::{ManifestError, Result};
 
+/// Main parser object.
+///
+/// Depending on the function you call, it either parses a manifest
+/// [from reader][crate::RiotManifest::from_reader] or [a file][crate::RiotManifest::from_path].
 #[derive(Debug, Default, Clone, PartialEq, Eq)]
 pub struct RiotManifest {
+    /// Parsed file header data.
+    ///
+    /// Stores information like [magic bytes](crate::Header::magic),
+    /// [version](crate::Header::major), [flags](crate::Header::flags),
+    /// [size](crate::Header::compressed_size), [offset](crate::Header::offset), etc.
     pub header: Header,
+    /// Parsed flatbuffer data.
+    ///
+    /// Stores all of the [flatbuffer entries][crate::entries], as well as the [parsed files][crate::File].
     pub data: ManifestData,
 }
 
 impl RiotManifest {
+    /// Loads data from a file and parses it.
+    ///
+    /// This is just a convenience method that [opens a file][std::fs::File::open],
+    /// [buffers it][std::io::BufReader] and calls [`RiotManifest::from_reader`].
+    ///
+    /// # Errors
+    ///
+    /// If reading a file fails, the error [`IoError`][crate::ManifestError::IoError] is
+    /// returned.
+    ///
+    /// If parsing fails, it propagates an error from [`RiotManifest::from_reader`].
+    ///
+    /// # Examples
+    ///
+    /// See
+    /// [parsing a manifest file from path](index.html#example-parsing-a-manifest-file-from-path).
+    ///
+    /// [`RiotManifest::from_reader`]: crate::RiotManifest::from_reader
     pub fn from_path<P>(path: P) -> Result<Self>
     where
         P: AsRef<Path>,
@@ -28,6 +58,38 @@ impl RiotManifest {
         Self::from_reader(&mut reader)
     }
 
+    /// Main parser method.
+    ///
+    /// Brief overview on how parsing the manifest is done:
+    /// - attempts to [parse the header][crate::Header::from_reader]
+    /// - [seeks][std::io::Seek] to the [offset](crate::Header::offset)
+    /// - reads [x amount](crate::Header::compressed_size) of bytes to buffer
+    /// - [decompresses][zstd::bulk::decompress] read bytes
+    /// - decompressed data is a [flatbuffer binary], that is then
+    /// [parsed][crate::ManifestData::parse].
+    ///
+    /// # Errors
+    ///
+    /// If parsing the header fails, it propagates an error from
+    /// [`Header::from_reader`][crate::Header::from_reader].
+    ///
+    /// If seeking to offset fails, the error [`SeekError`][crate::ManifestError::SeekError] is
+    /// returned.
+    ///
+    /// If converting [`compressed_size`](crate::Header::compressed_size) or
+    /// [`uncompressed_size`](crate::Header::uncompressed_size) to [`usize`] fails, the error
+    /// [`ConversionFailure`][crate::ManifestError::ConversionFailure] is returned.
+    ///
+    /// If reading compressed flatbuffer data fails, the error
+    /// [`IoError`][crate::ManifestError::IoError] is returned.
+    ///
+    /// If zstd decompression fails, the error
+    /// [`ZstdDecompressError`][crate::ManifestError::ZstdDecompressError] is returned.
+    ///
+    /// If parsing flatbuffer binary fails, it propagates an error from
+    /// [`ManifestData::parse`][crate::ManifestData::parse].
+    ///
+    /// [flatbuffer binary]: https://github.com/ev3nvy/rman-schema
     pub fn from_reader<R>(reader: &mut R) -> Result<Self>
     where
         R: Read + Seek,

src/parser/header.rs

@@ -5,19 +5,74 @@ use log::{debug, info, warn};
 
 use crate::{ManifestError, Result};
 
+/// File header.
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
 pub struct Header {
+    /// Magic bytes of the file.
+    ///
+    /// They are stored as [`u32`] and not as a string, which also means that it reads `RMAN` in
+    /// reverse because of endianness.
     pub magic: u32,
+    /// Major version of the manifest format.
+    ///
+    /// So far, it's only ever been 2.
+    ///
+    /// NOTE: The library logs if the version differs from 2 using the [log crate][log].
     pub major: u8,
+    /// Minor version of the manifest format.
+    ///
+    /// So far, it's only ever been 0.
+    ///
+    /// NOTE: The library logs if the version differs from 0 using the [log crate][log].
     pub minor: u8,
+    /// Manifest flags (no idea what any of them mean or do).
     pub flags: u16,
+    /// Offset to the compressed flatbuffer data.
     pub offset: u32,
+    /// Size of the parsed flatbuffer schema before decompression.
     pub compressed_size: u32,
+    /// Manifest id.
     pub manifest_id: u64,
+    /// Size of the parsed flatbuffer schema after decompression.
     pub uncompressed_size: u32,
 }
 
 impl Header {
+    /// Main header parser method.
+    ///
+    /// This method tries to parse the file header, and does some basic checks that it is indeed a
+    /// Riot Manifest file.
+    ///
+    /// It checks the [magic bytes](Header::magic), [version](Header::major),
+    /// [offset](Header::offset) and [compressed size](Header::compressed_size).
+    ///
+    /// # Errors
+    ///
+    /// If converting file size from [`usize`] fails, the error
+    /// [`ConversionFailure`][crate::ManifestError::ConversionFailure] is returned.
+    ///
+    /// If seeking to start (rewinding) fails, the error
+    /// [`SeekError`][crate::ManifestError::SeekError] is returned.
+    ///
+    /// If reading from io stream fails, the error [`IoError`][crate::ManifestError::IoError] is
+    /// returned.
+    ///
+    /// If magic bytes do not equal to `R`, `M`, `A` and `N`, the error
+    /// [`InvalidMagicBytes`][crate::ManifestError::InvalidMagicBytes] is returned.
+    ///
+    /// If major version does not equal 2, and the feature
+    /// [`version_error`](index.html#feature-version_error) is enabled, the error
+    /// [`InvalidMajor`][crate::ManifestError::InvalidMajor] is returned.
+    ///
+    /// If minor version does not equal 0, and the feature
+    /// [`version_error`](index.html#feature-version_error) is enabled, the error
+    /// [`InvalidMinor`][crate::ManifestError::InvalidMinor] is returned.
+    ///
+    /// If offset is smaller or larger than the file, the error
+    /// [`InvalidOffset`][crate::ManifestError::InvalidOffset] is returned.
+    ///
+    /// If compressed_size is smaller or larger than the file, the error
+    /// [`CompressedSizeTooLarge`][crate::ManifestError::CompressedSizeTooLarge] is returned.
     pub fn from_reader<R>(reader: &mut R) -> Result<Self>
     where
         R: Read + Seek,

src/parser/manifest.rs

@@ -5,14 +5,22 @@ use crate::generated::rman::root_as_manifest;
 use crate::File;
 use crate::Result;
 
+/// Stores all of the flatbuffer data, as well as the parsed files.
 #[derive(Debug, Default, Clone, PartialEq, Eq)]
 pub struct ManifestData {
+    /// Vector of [bundle entries][crate::entries::BundleEntry].
     pub bundle_entries: Vec<BundleEntry>,
+    /// Vector of [directory entries][crate::entries::DirectoryEntry].
     pub directory_entries: Vec<DirectoryEntry>,
+    /// Vector of [file entries][crate::entries::FileEntry].
     pub file_entries: Vec<FileEntry>,
+    /// Vector of [key entries][crate::entries::KeyEntry].
     pub key_entries: Vec<KeyEntry>,
+    /// Vector of [language entries][crate::entries::LanguageEntry].
     pub language_entries: Vec<LanguageEntry>,
+    /// Vector of [param entries][crate::entries::ParamEntry].
     pub param_entries: Vec<ParamEntry>,
+    /// Vector of [files][crate::File].
     pub files: Vec<File>,
 }
 
@@ -28,6 +36,22 @@ macro_rules! map_vector {
 }
 
 impl ManifestData {
+    /// Main flatbuffer parser method.
+    ///
+    /// This method tries to parse the entire flatbuffer binary.
+    ///
+    /// Yes, I know that a huge advantage of flatbuffers is the fact that they don't need to be
+    /// parsed. However parsing the data in our case allows us to more easly explore it's
+    /// contents and provides permanent objects so that the buffer can be discarded. Not to
+    /// mention the fact that it's still plenty fast. :^)
+    ///
+    /// # Errors
+    ///
+    /// If verifying the flatbuffer fails, the error
+    /// [`FlatbufferError`][crate::ManifestError::FlatbufferError] is returned.
+    ///
+    /// If parsing the [`File`][crate::File] fails, it propagates an error from
+    /// [`File::parse`][crate::File::parse].
     pub fn parse(bytes: &[u8]) -> Result<Self> {
         let manifest = root_as_manifest(bytes)?;