From 7bea6ede4c3d393994d456ff7a54b0866703ba16 Mon Sep 17 00:00:00 2001
From: PlexSheep <software@cscherr.de>
Date: Thu, 1 Feb 2024 23:21:01 +0100
Subject: [PATCH] update some documentation and move code around

---
 src/dumper.rs | 59 +++++++++++++++++++++++++++++----------------------
 src/main.rs   |  4 ++--
 2 files changed, 36 insertions(+), 27 deletions(-)

diff --git a/src/dumper.rs b/src/dumper.rs
index 6648f7c..3a8ba7d 100644
--- a/src/dumper.rs
+++ b/src/dumper.rs
@@ -1,9 +1,4 @@
-//! # Dump data
-//!
-//! This crate is part of [`pt`](../libpt/index.html), but can also be used as a standalone
-//! module.
-//!
-//! Hedu is made for hexdumping data. `libpt` offers a cli application using this module.
+//! # Underlying mechanisms of how hedu works with data
 
 use std::io::{prelude::*, Read, SeekFrom};
 
@@ -16,6 +11,23 @@ pub const LINE_SEP_HORIZ: char = '─';
 pub const LINE_SEP_VERT: char = '│';
 pub const CHAR_BORDER: &'static str = "|";
 
+pub trait DataSource: Read {
+    fn skip(&mut self, length: usize) -> std::io::Result<()>;
+}
+impl DataSource for std::io::Stdin {
+    fn skip(&mut self, _length: usize) -> std::io::Result<()> {
+        warn!("can't skip bytes for the stdin!");
+        Ok(())
+    }
+}
+impl DataSource for std::fs::File {
+    fn skip(&mut self, length: usize) -> std::io::Result<()> {
+        self.seek(SeekFrom::Current(length as i64))?;
+        // returns the new position from the start, we don't need it here.
+        Ok(())
+    }
+}
+
 #[derive(Debug)]
 pub struct Hedu {
     pub chars: bool,
@@ -33,6 +45,7 @@ pub struct Hedu {
 }
 
 impl Hedu {
+    /// create a new hedu struct, initializing all kinds of configs and values needed while running
     pub fn new(chars: bool, skip: usize, show_identical: bool, limit: usize) -> Self {
         Hedu {
             chars,
@@ -49,11 +62,15 @@ impl Hedu {
             first_iter: true,
         }
     }
+
+    /// print the display buffer to the stdout
     #[inline]
     pub fn display(&mut self) {
         println!("{}", self.display_buf);
         self.display_buf = String::new();
     }
+
+    /// display a separator line
     #[inline]
     pub fn sep(&mut self) {
         if self.chars {
@@ -63,11 +80,15 @@ impl Hedu {
         }
         self.display();
     }
+
+    /// display a newline
     #[inline]
     pub fn newline(&mut self) {
         self.display_buf += "\n";
         self.display();
     }
+
+    /// display the dump of a single line of data
     fn dump_a_line(&mut self) {
         self.display_buf += &format!("{:08X} {LINE_SEP_VERT} ", self.data_idx);
         if self.len != 0 {
@@ -105,6 +126,7 @@ impl Hedu {
         self.display();
     }
 
+    /// skip duplicate lines and display skip info
     fn skip_lines(&mut self, data: &mut dyn DataSource) -> Result<()> {
         trace!(buf = format!("{:?}", self.buf), "found a duplicating line");
         let start_line = self.data_idx;
@@ -128,6 +150,8 @@ impl Hedu {
         self.display();
         Ok(())
     }
+
+    /// dump a data sources contents according to the set configs
     pub fn dump(&mut self, data: &mut dyn DataSource) -> Result<()> {
         // skip a given number of bytes
         if self.skip > 0 {
@@ -188,6 +212,7 @@ impl Hedu {
         self.data_idx += self.len;
     }
 
+    /// read data from the data source
     fn rd_data(&mut self, data: &mut dyn DataSource) -> Result<()> {
         match data.read(&mut self.buf[self.alt_buf]) {
             Ok(mut len) => {
@@ -197,33 +222,17 @@ impl Hedu {
                 }
                 self.len = len;
                 self.adjust_counters();
-                return Ok(());
+                Ok(())
             }
             Err(err) => {
                 error!("error while reading data: {err}");
-                bail!(err)
+                Err(err.into())
             }
         }
     }
 }
 
-pub trait DataSource: Read {
-    fn skip(&mut self, length: usize) -> std::io::Result<()>;
-}
-impl DataSource for std::io::Stdin {
-    fn skip(&mut self, _length: usize) -> std::io::Result<()> {
-        warn!("can't skip bytes for the stdin!");
-        Ok(())
-    }
-}
-impl DataSource for std::fs::File {
-    fn skip(&mut self, length: usize) -> std::io::Result<()> {
-        self.seek(SeekFrom::Current(length as i64))?;
-        // returns the new position from the start, we don't need it here.
-        Ok(())
-    }
-}
-
+/// interpret characters for the --chars option
 fn mask_chars(c: char) -> char {
     if c.is_ascii_graphic() {
         return c;
diff --git a/src/main.rs b/src/main.rs
index d8377df..c5b3f8e 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -1,6 +1,6 @@
-//! # Executable for the hedu submodule
+//! # A simple hexdumper with a somewhat fancy format
 //!
-//! Dump data to a fancy format.
+//! Dump data from any readable source, such as the stdin or a file
 #![warn(clippy::pedantic)]
 
 use std::{fs::File, io::IsTerminal, path::PathBuf};