address error documentation lint (#641)

Author: demoray

src/image.rs

@@ -63,6 +63,13 @@ pub struct Block {
 }
 
 impl Header {
+    /// Reads a header from the provided file.
+    ///
+    /// # Errors
+    /// Returns an error if:
+    /// - The header cannot be read from the file
+    /// - The magic number or version is invalid
+    /// - The padding value is not zero
     pub fn read(mut src: &File) -> Result<Self> {
         let magic = src
             .read_u32::<LittleEndian>()
@@ -105,6 +112,12 @@ impl Header {
         Ok(bytes)
     }
 
+    /// Writes the header to the destination writer.
+    ///
+    /// # Errors
+    /// Returns an error if:
+    /// - The version is not supported
+    /// - The header cannot be written to the destination
     pub fn write<W>(&self, dst: &mut W) -> Result<()>
     where
         W: Write,
@@ -115,6 +128,12 @@ impl Header {
     }
 }
 
+/// Copies data from a source reader to a destination writer.
+///
+/// # Errors
+/// Returns an error if:
+/// - Reading from the source fails
+/// - Writing to the destination fails
 pub fn copy<R, W>(mut size: usize, src: &mut R, dst: &mut W) -> Result<()>
 where
     R: Read,
@@ -220,6 +239,13 @@ where
     }
 }
 
+/// Copies a memory block from the source reader to the destination writer.
+///
+/// # Errors
+/// Returns an error if:
+/// - Reading from the source fails
+/// - Writing to the destination fails
+/// - Size conversion from u64 to usize fails
 pub fn copy_block<R, W>(mut header: Header, src: &mut R, dst: &mut W) -> Result<()>
 where
     R: Read,
@@ -277,6 +303,12 @@ impl Image {
             .map_err(Error::Write)
     }
 
+    /// Creates a new Image with the specified version, source filename, and destination filename.
+    ///
+    /// # Errors
+    /// Returns an error if:
+    /// - The source file cannot be opened for reading
+    /// - The destination file cannot be created or opened for writing
     pub fn new(version: u32, src_filename: &Path, dst_filename: &Path) -> Result<Self> {
         let src = OpenOptions::new()
             .read(true)
@@ -288,6 +320,10 @@ impl Image {
         Ok(Self { version, src, dst })
     }
 
+    /// Writes multiple memory blocks to the destination file.
+    ///
+    /// # Errors
+    /// Returns an error if writing any block fails
     pub fn write_blocks(&mut self, blocks: &[Block]) -> Result<()> {
         for block in blocks {
             self.write_block(block)

src/iomem.rs

@@ -8,18 +8,21 @@ use std::{fs::read_to_string, io::Error as IoError, path::Path};
 pub enum Error {
     #[error("unable to read from /proc/iomem")]
     Io(#[from] IoError),
-
     #[error("unable to parse value")]
     Parse(#[from] ParseIntError),
-
     #[error("unable to parse line: {0}")]
     ParseLine(String),
-
     #[error("need CAP_SYS_ADMIN to read /proc/iomem")]
     PermissionDenied,
 }
 
 /// Parse /proc/iomem and return System RAM memory ranges
+///
+/// # Errors
+/// Returns an error if:
+/// - Failed to read the /proc/iomem file
+/// - Failed to parse memory ranges from the file content
+/// - Permission denied when trying to read /proc/iomem (requires `CAP_SYS_ADMIN`)
 pub fn parse() -> Result<Vec<Range<u64>>, Error> {
     parse_file(Path::new("/proc/iomem"))
 }

src/snapshot.rs

@@ -208,16 +208,23 @@ impl<'a, 'b> Snapshot<'a, 'b> {
     }
 
     fn create_source(&self, src: &Source) -> Result<()> {
-        match src {
+        match *src {
             Source::ProcKcore => self.kcore(),
             Source::DevCrash => self.phys(Path::new("/dev/crash")),
             Source::DevMem => self.phys(Path::new("/dev/mem")),
-            Source::Raw(s) => self.phys(s),
+            Source::Raw(ref s) => self.phys(s),
         }
         .map_err(|e| Error::UnableToCreateSnapshotFromSource(Box::new(e), src.clone()))
     }
 
     /// Create a memory snapshot
+    ///
+    /// # Errors
+    /// Returns an error if:
+    /// - No source is available for creating the snapshot
+    /// - There is a failure reading from the specified source
+    /// - The estimated disk usage exceeds the specified limits
+    /// - Failed to create or write to the destination file
     pub fn create(&self) -> Result<()> {
         if let Some(src) = self.source {
             self.create_source(src)?;

src/upload/blobstore.rs

@@ -170,6 +170,11 @@ pub struct BlobUploader {
 }
 
 impl BlobUploader {
+    /// Create a new ``BlobUploader`` from a SAS URL.
+    ///
+    /// # Errors
+    /// Returns an error if:
+    /// - The URL cannot be parsed as a valid Azure SAS URL
     pub fn new(sas: &Url) -> Result<Self> {
         let blob_client = BlobClient::from_sas_url(sas)?;
         Ok(Self::with_blob_client(blob_client))
@@ -222,9 +227,16 @@ impl BlobUploader {
     }
 
     /// Upload a file to Azure Blob Store using a fully qualified SAS token
+    ///
+    /// # Errors
+    /// Returns an error if:
+    /// - The file cannot be opened or read
+    /// - The file size cannot be converted to a usize
+    /// - The file is too large for Azure Blob Storage
+    /// - There is a failure during the upload process
+    /// - There is a failure finalizing the block list
     pub async fn upload_file(mut self, filename: &Path) -> Result<()> {
         let file = File::open(filename).await?;
-
         let file_size = file
             .metadata()
             .await?

src/upload/http.rs

@@ -22,6 +22,12 @@ pub enum Error {
 }
 
 /// Upload a file via HTTP PUT
+///
+/// # Errors
+/// Returns an error if:
+/// - The file cannot be opened or read
+/// - There is a failure making the HTTP request
+/// - The server returns an unexpected status code
 #[cfg(feature = "put")]
 pub async fn put(filename: &Path, url: &Url) -> Result<(), Error> {
     let file = File::open(&filename)