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,9 @@
+#![warn(missing_docs)]
+//! Bmap-rs is an aplication that handle the use of bmap crate.
+//!
+//! Currently it allows you to copy files or falsh block devices
+//! safely.
+//!
 use anyhow::{anyhow, bail, Context, Result};
 use bmap::{Bmap, Discarder, SeekForward};
 use clap::Parser;

bmap/src/bmap.rs

@@ -2,33 +2,40 @@ 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 {
+    /// This HashType means we are using the Sha256 algorithm to create the checksums.
     Sha256,
 }
 
+/// Value holder for the block's checksum.
 #[derive(Copy, Clone, Debug, PartialEq, Eq, EnumDiscriminants)]
 #[non_exhaustive]
 pub enum HashValue {
+    /// Holder with the size of a Sha256 hash.
     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 it's checksum.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct BlockRange {
     offset: u64,
@@ -37,19 +44,23 @@ 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
     }
 
+    /// Returns the offset of the block.
     pub fn offset(&self) -> u64 {
         self.offset
     }
 
+    /// Returns the length of the block.
     pub fn length(&self) -> u64 {
         self.length
     }
 }
 
+/// Contains the bmap file information, including a vector of blocks.
 #[derive(Clone, Debug)]
 pub struct Bmap {
     image_size: u64,
@@ -61,58 +72,80 @@ pub struct Bmap {
 }
 
 impl Bmap {
+    /// Returns a BmapBuilder.
     pub fn builder() -> BmapBuilder {
         BmapBuilder::default()
     }
 
+    /// Parse a Bmap from a xml file.
     pub fn from_xml(xml: &str) -> Result<Self, xml::XmlError> {
         xml::from_xml(xml)
     }
 
+    /// Returns the image size.
     pub fn image_size(&self) -> u64 {
         self.image_size
     }
 
+    /// Returns the size of the blocks.
     pub const fn block_size(&self) -> u64 {
         self.block_size
     }
 
+    /// Returns the number of blocks.
     pub fn blocks(&self) -> u64 {
         self.blocks
     }
 
+    /// Returns the number of mapped blocks.
     pub fn mapped_blocks(&self) -> u64 {
         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 indicates which field originated the error.
 #[derive(Clone, Debug, Error)]
 pub enum BmapBuilderError {
+    /// Error that indicates image size is missing.
     #[error("Image size missing")]
     MissingImageSize,
+    /// Error that indicates block size is missing.
     #[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 that indicates the checksum hash type is missing.
     #[error("Checksum type missing")]
     MissingChecksumType,
+    /// Error that indicates there are not BlockRanges in the vector.
     #[error("No block ranges")]
     NoBlockRanges,
 }
 
+/// Intermediary tool to generate the a 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>,
@@ -124,31 +157,37 @@ pub struct BmapBuilder {
 }
 
 impl BmapBuilder {
+    /// Modify the image size inside of an Option. Returns the BmapBuilder.
     pub fn image_size(&mut self, size: u64) -> &mut Self {
         self.image_size = Some(size);
         self
     }
 
+    /// Modify the size of the blocks as an Option. Returns the BmapBuilder.
     pub fn block_size(&mut self, block_size: u64) -> &mut Self {
         self.block_size = Some(block_size);
         self
     }
 
+    /// Modify the number of blocks inside of an Option. Returns the BmapBuilder.
     pub fn blocks(&mut self, blocks: u64) -> &mut Self {
         self.blocks = Some(blocks);
         self
     }
 
+    /// Modify the number of mapped blocks inside of an Option. Returns the BmapBuilder.
     pub fn mapped_blocks(&mut self, blocks: u64) -> &mut Self {
         self.mapped_blocks = Some(blocks);
         self
     }
 
+    /// Modify the type of Hash used for the checksum inside of an Option. Returns the BmapBuilder.
     pub fn checksum_type(&mut self, checksum_type: HashType) -> &mut Self {
         self.checksum_type = Some(checksum_type);
         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 +196,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 +207,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

@@ -8,10 +8,12 @@ pub struct Discarder<R: Read> {
 }
 
 impl<R: Read> Discarder<R> {
+    /// Returns a new Discarder wrapping the reader.
     pub fn new(reader: R) -> Self {
         Self { reader }
     }
 
+    /// Returns the reader wrapped in the Discarder.
     pub fn into_inner(self) -> R {
         self.reader
     }

bmap/src/lib.rs

@@ -1,3 +1,6 @@
+#![warn(missing_docs)]
+//! Bmap is a library for Rust that allows you to copy files
+//! or flah block devices safely.
 mod bmap;
 pub use crate::bmap::*;
 mod discarder;
@@ -10,6 +13,7 @@ use std::io::{Read, Seek, SeekFrom, Write};
 
 /// Trait that can only seek further forwards
 pub trait SeekForward {
+    /// Seek forwards
     fn seek_forward(&mut self, offset: u64) -> IOResult<()>;
 }
 
@@ -20,18 +24,26 @@ impl<T: Seek> SeekForward for T {
     }
 }
 
+/// The error type returned by copy functions.
 #[derive(Debug, Error)]
 pub enum CopyError {
+    /// Error while reading data.
     #[error("Failed to Read: {0}")]
     ReadError(std::io::Error),
+    /// Error while writing data.
     #[error("Failed to Write: {0}")]
     WriteError(std::io::Error),
+    /// Errors because the checksums does not match.
     #[error("Checksum error")]
     ChecksumError,
+    /// Errors because an unexpected end of file was encountered.
     #[error("Unexpected EOF on input")]
     UnexpectedEof,
 }
 
+/// Copy a file into another or flash a block device, using a Bmap file.
+///
+/// For each block checks it's checksum.
 pub fn copy<I, O>(input: &mut I, output: &mut O, map: &Bmap) -> Result<(), CopyError>
 where
     I: Read + SeekForward,