improved documentation; code cleanup; set deny missing_docs

src/lib/compression.rs

@@ -52,7 +52,7 @@ impl fmt::Display for CompressionAlgorithm {
     }
 }
 
-/// decompresses a buffer with the given [CompressionAlgorithm].
+/// Decompresses a buffer with the given [CompressionAlgorithm].
 pub fn decompress_buffer<C>(buffer: &[u8], compression_algorithm: C) -> Result<Vec<u8>>
 where
 	C: Borrow<CompressionAlgorithm>,
@@ -74,6 +74,7 @@ where
     }
 }
 
+/// Decompresses a reader with the given [CompressionAlgorithm].
 pub fn decompress_reader<C, R>(input: &mut R, compression_algorithm: C) -> Result<Box<dyn Read + Send + '_>>
 where
 	C: Borrow<CompressionAlgorithm>,

src/lib/constants.rs

@@ -89,6 +89,7 @@ pub(crate) const ERROR_ZFFREADER_MISSING_OBJECT: &str = "Missing object number i
 // Default values
 pub(crate) const DEFAULT_LENGTH_HEADER_IDENTIFIER: usize = 4;
 pub(crate) const DEFAULT_LENGTH_VALUE_HEADER_LENGTH: usize = 8;
+
 /// The number of the first object in a zff container.
 pub const INITIAL_OBJECT_NUMBER: u64 = 1;
 
@@ -174,7 +175,9 @@ pub(crate) const METADATA_BTIME: &str = "btime";
 
 
 // - ChunkMap
+/// Table name for the redb chunkmap
 pub const CHUNK_MAP_TABLE: TableDefinition<&[u8; 32], u64> = TableDefinition::new("map");
+/// Table name for the redb preloaded chunkmap
 pub const PRELOADED_CHUNK_MAP_TABLE: TableDefinition<u64, u64> = TableDefinition::new("preloaded_map");
 
 // - Encryption parameters

src/lib/error.rs

@@ -29,7 +29,9 @@ use cbc::cipher::block_padding::UnpadError as AesCbcError;
 /// The main error-type of this crate.
 #[derive(Debug)]
 pub struct ZffError {
+	/// A detailed error message.
 	pub details: String,
+	/// The appropriate [ZffErrorKind].
 	pub kind: ZffErrorKind,
 }
 
@@ -283,6 +285,20 @@ impl ZffError {
 		}
 	}
 
+	/// Creates a new crate-related "value not in map" error.
+	/// # Example
+	/// ```
+	/// use zff::{ZffError, Result};
+	/// fn my_func() -> Result<()> {
+	///     let decode_error = ZffError::new_not_in_map_error("the appropriate value is not in map!");
+	///        Err(decode_error)
+	/// }
+	/// fn main() {
+	///        match my_func() {
+	///            Err(x) => println!("It work's! Your custom error message is: {}", x),
+	///            _ => ()
+	///        }
+	/// }
 	pub fn new_not_in_map_error() -> ZffError {
 		ZffError {
 			kind: ZffErrorKind::ValueNotInMap,

src/lib/footer/file_footer.rs

@@ -124,6 +124,7 @@ impl FileFooter {
 		vec
 	}
 
+	/// encrypts the file footer by the given encryption information and returns the encrypted file footer.
 	pub fn encrypt_directly<E>(&self, encryption_information: E) -> Result<Vec<u8>>
 	where
 		E: Borrow<EncryptionInformation>

src/lib/footer/main_footer.rs

@@ -104,6 +104,7 @@ impl MainFooter {
 		Some(self.description_notes.as_ref()?)
 	}
 
+	/// Returns a reference of the global chunkmap table.
 	pub fn chunk_maps(&self) -> &BTreeMap<u64, u64> {
 		&self.chunk_maps
 	}

src/lib/footer/mod.rs

@@ -1,8 +1,8 @@
 // - modules
 mod main_footer;
 mod segment_footer;
-pub mod file_footer;
-pub mod object_footer;
+mod file_footer;
+mod object_footer;
 
 // - re-exports -- this section contains the footer of the current zff version.
 pub use main_footer::*;

src/lib/footer/object_footer.rs

@@ -97,20 +97,23 @@ impl ObjectFooter {
 		}
 	}
 
+	/// Returns the appropriate object number.
 	pub fn object_number(&self) -> u64 {
 		match self {
 			ObjectFooter::Physical(footer) => footer.object_number,
 			ObjectFooter::Logical(footer) => footer.object_number,
 		}
 	}
 
+	/// Returns the appropriate acquisition start timestamp.
 	pub fn acquisition_start(&self) -> u64 {
 		match self {
 			ObjectFooter::Physical(footer) => footer.acquisition_start,
 			ObjectFooter::Logical(footer) => footer.acquisition_start,
 		}
 	}
 
+	/// Returns the appropriate acquisition end timestamp.
 	pub fn acquisition_end(&self) -> u64 {
 		match self {
 			ObjectFooter::Physical(footer) => footer.acquisition_end,
@@ -248,17 +251,21 @@ impl EncryptedObjectFooter {
 
 
 
-/// Encrypted footer.
+/// Represents an encrypted object footer of a physical object.
 #[derive(Debug, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "serde", derive(Serialize))]
 #[cfg_attr(feature = "serde", derive(Deserialize))]
 pub struct EncryptedObjectFooterPhysical {
+	/// The appropriate footer version.
 	pub version: u8,
+	/// The appropriate object number.
 	pub object_number: u64,
+	/// The underlying data in encrypted form.
 	pub encrypted_data: Vec<u8>,
 }
 
 impl EncryptedObjectFooterPhysical {
+	/// Creates a new [EncryptedObjectFooterPhysical] by the given values.
 	pub fn new(version: u8, object_number: u64, encrypted_data: Vec<u8>) -> Self {
 		Self {
 			version,
@@ -267,7 +274,7 @@ impl EncryptedObjectFooterPhysical {
 		}
 	}
 
-	/// tries to decrypt the ObjectFooter. If an error occures, the EncryptedObjectFooterPhysical is still available.
+	/// Tries to decrypt the ObjectFooter. If an error occures, the EncryptedObjectFooterPhysical is still available.
 	pub fn decrypt<A, K>(&self, key: K, algorithm: A) -> Result<ObjectFooterPhysical>
 	where
 		A: Borrow<EncryptionAlgorithm>,
@@ -292,7 +299,7 @@ impl EncryptedObjectFooterPhysical {
 			hash_header))
 	}
 
-	/// tries to decrypt the ObjectFooter. Consumes the EncryptedObjectFooterPhysical, regardless of whether an error occurs or not.
+	/// Tries to decrypt the ObjectFooter. Consumes the EncryptedObjectFooterPhysical, regardless of whether an error occurs or not.
 	pub fn decrypt_and_consume<A, K>(self, key: K, algorithm: A) -> Result<ObjectFooterPhysical>
 	where
 		A: Borrow<EncryptionAlgorithm>,
@@ -370,13 +377,21 @@ impl HeaderCoding for EncryptedObjectFooterPhysical {
 #[derive(Debug,Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "serde", derive(Serialize))]
 pub struct ObjectFooterPhysical {
+	/// The version of the footer.
 	pub version: u8,
+	/// The object number of the footer.
 	pub object_number: u64,
+	/// The acquisition start timestamp of the footer.
 	pub acquisition_start: u64,
+	/// The acquisition end timestamp of the footer.
 	pub acquisition_end: u64,
+	/// The original length of the data.
 	pub length_of_data: u64,
+	/// The first used chunk number in this object.
 	pub first_chunk_number: u64,
+	/// The total number of chunks used in this object.
 	pub number_of_chunks: u64,
+	/// The appropriate [crate::header::HashHeader].
 	pub hash_header: HashHeader,
 }
 
@@ -414,6 +429,7 @@ impl ObjectFooterPhysical {
 		vec
 	}
 
+	/// encrypts the object footer by the given encryption information and returns the encrypted object footer.
 	pub fn encrypt_directly<E>(&self, encryption_information: E) -> Result<Vec<u8>>
 	where
 		E: Borrow<EncryptionInformation>
@@ -515,17 +531,21 @@ impl HeaderCoding for ObjectFooterPhysical {
 	}
 }
 
-/// Encrypted footer.
+/// An object footer for a logical object in encrypted form.
 #[derive(Debug, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "serde", derive(Serialize))]
 #[cfg_attr(feature = "serde", derive(Deserialize))]
 pub struct EncryptedObjectFooterLogical {
+	/// The footer version.
 	pub version: u8,
+	/// The appropriate object number.
 	pub object_number: u64,
+	/// the encrypted data of this footer
 	pub encrypted_data: Vec<u8>,
 }
 
 impl EncryptedObjectFooterLogical {
+	/// Creates a new [EncryptedObjectFooterLogical] by the given values.
 	pub fn new(version: u8, object_number: u64, encrypted_data: Vec<u8>) -> Self {
 		Self {
 			version,
@@ -534,7 +554,7 @@ impl EncryptedObjectFooterLogical {
 		}
 	}
 
-	/// tries to decrypt the ObjectFooter. If an error occures, the EncryptedObjectFooterPhysical is still available.
+	/// Tries to decrypt the ObjectFooter. If an error occures, the EncryptedObjectFooterPhysical is still available.
 	pub fn decrypt<A, K>(&self, key: K, algorithm: A) -> Result<ObjectFooterLogical>
 	where
 		A: Borrow<EncryptionAlgorithm>,
@@ -561,7 +581,7 @@ impl EncryptedObjectFooterLogical {
 			file_footer_offsets))
 	}
 
-	/// tries to decrypt the ObjectFooter. Consumes the EncryptedObjectFooterPhysical, regardless of whether an error occurs or not.
+	/// Tries to decrypt the ObjectFooter. Consumes the EncryptedObjectFooterPhysical, regardless of whether an error occurs or not.
 	pub fn decrypt_and_consume<A, K>(self, key: K, algorithm: A) -> Result<ObjectFooterLogical>
 	where
 		A: Borrow<EncryptionAlgorithm>,
@@ -780,6 +800,7 @@ impl ObjectFooterLogical {
 		vec
 	}
 
+	/// encrypts the object footer by the given encryption information and returns the encrypted object footer.
 	pub fn encrypt_directly<E>(&self, encryption_information: E) -> Result<Vec<u8>>
 	where
 		E: Borrow<EncryptionInformation>
@@ -886,5 +907,4 @@ impl HeaderCoding for ObjectFooterLogical {
 			file_footer_segment_numbers, 
 			file_footer_offsets))
 	}
-
 }

src/lib/footer/segment_footer.rs

@@ -32,11 +32,17 @@ use serde::{
 #[cfg_attr(feature = "serde", derive(Deserialize))]
 #[cfg_attr(feature = "serde", derive(Serialize))]
 pub struct SegmentFooter {
+	/// The footer version
 	pub version: u8,
+	/// The total length of the segment.
 	pub length_of_segment: u64,
+	/// A [HashMap] containing the object number and the appropriate offset of the [crate::header::ObjectHeader].
 	pub object_header_offsets: HashMap<u64, u64>, //<object number, offset>,
+	/// A [HashMap] containing the object number and the appropriate offset of the [crate::footer::ObjectFooter].
 	pub object_footer_offsets: HashMap<u64, u64>, //<object number, offset>,
+	/// [BTreeMap] containing the chunk number and the appropriate offset of the chunkmaps.
 	pub chunk_map_table: BTreeMap<u64, u64>, //<highest chunk number, offset>
+	/// The first chunk number which was used in this segment.
 	pub first_chunk_number: u64,
 	/// The offset where the footer starts.
 	pub footer_offset: u64,

src/lib/header/chunk_header.rs

@@ -29,15 +29,22 @@ use serde::{
 	Serialize,
 };
 
+/// The appropriate flags for each chunk.
 #[derive(Debug,Clone,Default)]
 #[cfg_attr(feature = "serde", derive(Deserialize))]
 #[cfg_attr(feature = "serde", derive(Serialize))]
 pub struct ChunkHeaderFlags {
+	/// is set, if an read error is occured and the data in this chunk could be corrupted.
 	pub error: bool,
+	/// is set, if the data in the chunk are compressed.
 	pub compression: bool,
+	/// is set, if the chunk contains the same bytes.
 	pub same_bytes: bool,
+	/// is set, if this chunk is a duplicate of an other chunk.
 	pub duplicate: bool,
+	/// is set, if the chunk data is encrypted.
 	pub encryption: bool,
+	/// is set, if this is a placeholder chunk of an empty file.
 	pub empty_file: bool,
 }
 
@@ -74,10 +81,15 @@ impl ChunkHeaderFlags {
 #[cfg_attr(feature = "serde", derive(Deserialize))]
 #[cfg_attr(feature = "serde", derive(Serialize))]
 pub struct ChunkHeader {
+	/// the header version.
 	pub version: u8,
+	/// the appropriate chunk number.
 	pub chunk_number: u64,
+	/// the appropriate size of the chunk data (in the final optionally compressed and encrypted form).
 	pub chunk_size: u64,
+	/// the appropriate chunk header flags.
 	pub flags: ChunkHeaderFlags,
+	/// the crc32 value to ensure (a bit) integrity.
 	pub crc32: u32,
 }
 
@@ -108,7 +120,7 @@ impl ChunkHeader {
 		}
 	}
 
-	/// tries to encrypt the ChunkHeader. If an error occures, the unencrypted ChunkHeader is still available.
+	/// Tries to encrypt the ChunkHeader. If an error occures, the unencrypted ChunkHeader is still available.
 	pub fn encrypt<A, K>(&self, key: K, algorithm: A) -> Result<EncryptedChunkHeader>
 	where
 		A: Borrow<EncryptionAlgorithm>,
@@ -118,7 +130,7 @@ impl ChunkHeader {
 		Ok(EncryptedChunkHeader::new(self.chunk_number, self.chunk_size, self.flags.clone(), crc32))
 	}
 
-	/// tries to encrypt the ChunkHeader. Consumes theunencrypted ChunkHeader, regardless of whether an error occurs or not.
+	/// Tries to encrypt the ChunkHeader. Consumes theunencrypted ChunkHeader, regardless of whether an error occurs or not.
 	pub fn encrypt_and_consume<A, K>(self, key: K, algorithm: A) -> Result<EncryptedChunkHeader>
 	where
 		A: Borrow<EncryptionAlgorithm>,
@@ -197,15 +209,20 @@ impl ChunkHeader {
 	}
 }
 
-/// Header for chunk data (contains encrypted crc32 and ed25519 signature).
+/// Header for (encrypted) chunk data (contains encrypted crc32 and ed25519 signature).
 #[derive(Debug,Clone)]
 #[cfg_attr(feature = "serde", derive(Deserialize))]
 #[cfg_attr(feature = "serde", derive(Serialize))]
 pub struct EncryptedChunkHeader {
+	/// the header version.
 	pub version: u8,
+	/// the appropriate chunk number
 	pub chunk_number: u64,
+	/// the appropriate size of the chunk data (in the final optionally compressed and encrypted form).
 	pub chunk_size: u64,
+	/// the appropriate chunk header flags.
 	pub flags: ChunkHeaderFlags,
+	/// the encrypted crc32 value.
 	pub crc32: Vec<u8>,
 }