Add in code documentation

Add documentiation as special comments to be formatted with rustdoc.
`#![warn(missing_docs)]` will raise a warning in compiling time if the
docs expected are not satisfied.

Signed-off-by: Rafael Garcia Ruiz <[email protected]>

bmap-rs/src/main.rs

@@ -1,3 +1,6 @@
+//! Bmap-rs is an application that handles the use of bmap crate.
+//!
+//! It allows you to copy files or flash block devices safely.
 use anyhow::{anyhow, bail, Context, Result};
 use bmap::{Bmap, Discarder, SeekForward};
 use clap::Parser;

bmap/src/bmap.rs

@@ -2,33 +2,38 @@ use strum::{Display, EnumDiscriminants, EnumString};
 use thiserror::Error;
 mod xml;
 
+/// Hash type to be used to build the checksum at blocks.
 #[derive(Copy, Clone, Debug, PartialEq, Eq, EnumString, Display)]
 #[strum(serialize_all = "lowercase")]
 #[non_exhaustive]
 pub enum HashType {
     Sha256,
 }
 
+/// Value holder for the block's checksum.
 #[derive(Copy, Clone, Debug, PartialEq, Eq, EnumDiscriminants)]
 #[non_exhaustive]
 pub enum HashValue {
     Sha256([u8; 32]),
 }
 
 impl HashValue {
+    /// Returns the hash type used  in the HashValue.
     pub fn to_type(&self) -> HashType {
         match self {
             HashValue::Sha256(_) => HashType::Sha256,
         }
     }
 
+    /// Returns the value of the checksum in the HashValue.
     pub fn as_slice(&self) -> &[u8] {
         match self {
             HashValue::Sha256(v) => v,
         }
     }
 }
 
+/// Reference to a mapped block of data that contain its checksum.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct BlockRange {
     offset: u64,
@@ -37,6 +42,7 @@ pub struct BlockRange {
 }
 
 impl BlockRange {
+    /// Returns the checksum of the data mapped in the range of the block.
     pub fn checksum(&self) -> HashValue {
         self.checksum
     }
@@ -50,6 +56,7 @@ impl BlockRange {
     }
 }
 
+/// Contains the bmap file information, including a vector of blocks.
 #[derive(Clone, Debug)]
 pub struct Bmap {
     image_size: u64,
@@ -61,6 +68,7 @@ pub struct Bmap {
 }
 
 impl Bmap {
+    /// Returns a BmapBuilder.
     pub fn builder() -> BmapBuilder {
         BmapBuilder::default()
     }
@@ -77,6 +85,7 @@ impl Bmap {
         self.block_size
     }
 
+    /// Returns the number of blocks.
     pub fn blocks(&self) -> u64 {
         self.blocks
     }
@@ -85,34 +94,47 @@ impl Bmap {
         self.mapped_blocks
     }
 
+    /// Returns the type of Hash used for the checksum.
     pub fn checksum_type(&self) -> HashType {
         self.checksum_type
     }
 
+    /// Returns an iterator of BlockRange.
     pub fn block_map(&self) -> impl ExactSizeIterator + Iterator<Item = &BlockRange> {
         self.blockmap.iter()
     }
+
+    /// Returns the total size of mapped memory, it can be bigger than the image size.
     pub fn total_mapped_size(&self) -> u64 {
         self.block_size * self.mapped_blocks
     }
 }
 
+/// The error type returned by BmapBuilder.
+///
+/// This error indicates that the Bmap could not be built correctly. It also points at the field that originated the error.
 #[derive(Clone, Debug, Error)]
 pub enum BmapBuilderError {
     #[error("Image size missing")]
     MissingImageSize,
     #[error("Block size missing")]
     MissingBlockSize,
+    /// Error that indicates the number of blocks is missing.
     #[error("Blocks missing")]
     MissingBlocks,
+    /// Error that indicates the number of mapped blocks is missing.
     #[error("Mapped blocks missing")]
     MissingMappedBlocks,
     #[error("Checksum type missing")]
     MissingChecksumType,
+    /// Error that indicates there are not BlockRanges in the vector.
     #[error("No block ranges")]
     NoBlockRanges,
 }
 
+/// Intermediary tool to generate Bmap.
+///
+/// Contains the same data fields as a Bmap, but most of them as Option. Allowing a progressive parsing and then a casting into Bmap.
 #[derive(Clone, Debug, Default)]
 pub struct BmapBuilder {
     image_size: Option<u64>,
@@ -149,6 +171,7 @@ impl BmapBuilder {
         self
     }
 
+    /// Add a BlockRange to the vector indicating start, end and checksum. Needs Blocksize and Image to be set first. Returns the BmapBuilder.
     pub fn add_block_range(&mut self, start: u64, end: u64, checksum: HashValue) -> &mut Self {
         let bs = self.block_size.expect("Blocksize needs to be set first");
         let total = self.image_size.expect("Image size needs to be set first");
@@ -157,6 +180,7 @@ impl BmapBuilder {
         self.add_byte_range(offset, length, checksum)
     }
 
+    /// Add a BlockRange to the vector indicating offset, length and checksum.  Returns the BmapBuilder.
     pub fn add_byte_range(&mut self, offset: u64, length: u64, checksum: HashValue) -> &mut Self {
         let range = BlockRange {
             offset,
@@ -167,6 +191,7 @@ impl BmapBuilder {
         self
     }
 
+    /// Returns a Bmap or an Error as a Result.
     pub fn build(self) -> Result<Bmap, BmapBuilderError> {
         let image_size = self.image_size.ok_or(BmapBuilderError::MissingImageSize)?;
         let block_size = self.block_size.ok_or(BmapBuilderError::MissingBlockSize)?;

bmap/src/discarder.rs

@@ -2,7 +2,7 @@ use crate::SeekForward;
 use std::io::Read;
 use std::io::Result as IOResult;
 
-/// Adaptor that implements SeekForward on types only implementing Read by discarding data
+/// Adaptor that implements SeekForward on types only implementing Read by discarding data.
 pub struct Discarder<R: Read> {
     reader: R,
 }

bmap/src/lib.rs

@@ -1,3 +1,5 @@
+//! Bmap is a library for Rust that allows you to copy files
+//! or flash block devices safely.
 mod bmap;
 pub use crate::bmap::*;
 mod discarder;
@@ -20,6 +22,7 @@ impl<T: Seek> SeekForward for T {
     }
 }
 
+/// The error type returned by copy functions.
 #[derive(Debug, Error)]
 pub enum CopyError {
     #[error("Failed to Read: {0}")]
@@ -32,6 +35,9 @@ pub enum CopyError {
     UnexpectedEof,
 }
 
+/// Copy a file into another or flash a block device, using a Bmap file.
+///
+/// For each block checks its checksum.
 pub fn copy<I, O>(input: &mut I, output: &mut O, map: &Bmap) -> Result<(), CopyError>
 where
     I: Read + SeekForward,