From 72410d3d343ff75fb5f1425cc168cf06497a3810 Mon Sep 17 00:00:00 2001
From: Ral <noreply@git.tinkeral.ch>
Date: Fri, 28 Jul 2023 21:28:09 +0200
Subject: [PATCH] Some more documentation

---
 src/args.rs     | 3 ++-
 src/checksum.rs | 6 +++---
 src/i2c.rs      | 2 ++
 src/io.rs       | 2 ++
 src/std.rs      | 2 ++
 5 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/src/args.rs b/src/args.rs
index de05e6d..83eea48 100644
--- a/src/args.rs
+++ b/src/args.rs
@@ -4,6 +4,7 @@ fn hex_address(a: &str) -> Result<u16, std::num::ParseIntError> {
     u16::from_str_radix(a.trim_start_matches("0x"), 16)
 }
 
+/// Command line argument definitions.
 #[derive(Parser, Debug)]
 #[command(version, about, long_about = None, next_line_help = true, arg_required_else_help(true))]
 pub struct Args {
@@ -15,7 +16,7 @@ pub struct Args {
     #[arg(short, long, default_value = "0x50", value_parser = hex_address)]
     pub address: u16,
 
-    /// Number of 128-byte blocks to read, defaults to autodetect from data
+    /// Number of 128-byte blocks to read, defaults to autodetect from data.
     #[arg(short, long, default_value = None)]
     pub blocks: Option<usize>,
 }
diff --git a/src/checksum.rs b/src/checksum.rs
index 424cfc7..9dc0234 100644
--- a/src/checksum.rs
+++ b/src/checksum.rs
@@ -1,15 +1,15 @@
-// Compute the checksum over the bytes of a block.
+/// Compute the checksum over the bytes of a block.
 #[allow(clippy::cast_possible_truncation)]
 pub fn checksum(bytes: &[u8]) -> u8 {
     bytes.iter().fold(0u32, |x, y| x + u32::from(*y)) as u8
 }
 
-// Validate the checksum
+/// Check if the checksum is valid.
 pub fn valid_checksum(bytes: &[u8]) -> bool {
     checksum(bytes) == 0x00
 }
 
-// Print the checksum to stderr
+/// Print the checksum to stderr.
 pub fn print_checksum(bytes: &[u8]) {
     let cs = checksum(bytes);
     eprintln!("  Checksum is: {cs}");
diff --git a/src/i2c.rs b/src/i2c.rs
index e30279b..364715a 100644
--- a/src/i2c.rs
+++ b/src/i2c.rs
@@ -3,6 +3,7 @@ use i2cdev::linux::{LinuxI2CDevice, LinuxI2CMessage};
 use std::thread;
 use std::time::Duration;
 
+/// Read a fixed-size block of binary data from an i2c device.
 pub fn read_from_bus(
     i2c_device: &str,
     slave_address: u16,
@@ -25,6 +26,7 @@ pub fn read_from_bus(
     }
 }
 
+/// Write a fixed-size block of binary data to an i2c device.
 pub fn write_to_bus(
     i2c_device: &str,
     slave_address: u16,
diff --git a/src/io.rs b/src/io.rs
index 05bef3a..23899c2 100644
--- a/src/io.rs
+++ b/src/io.rs
@@ -3,6 +3,8 @@ use crate::checksum::print_checksum;
 /// Size of an EDID block in bytes.
 pub const BLOCK_SIZE: usize = 128;
 
+/// Read an EDID binary blob block by block. Check the first block for the
+/// number of extension blocks that should follow and try to read them all.
 pub fn block_by_block_read(
     blocks: Option<usize>,
     read: impl Fn(u8, usize) -> Result<Vec<u8>, std::io::Error>,
diff --git a/src/std.rs b/src/std.rs
index 273020b..375a12f 100644
--- a/src/std.rs
+++ b/src/std.rs
@@ -1,5 +1,6 @@
 use std::io::{self, Read, Write};
 
+/// Read a fixed-size block of binary data from stdin.
 pub fn read_from_stdin(data_length: usize) -> Result<Vec<u8>, std::io::Error> {
     // Buffer to read into
     let mut data = vec![0; data_length];
@@ -8,6 +9,7 @@ pub fn read_from_stdin(data_length: usize) -> Result<Vec<u8>, std::io::Error> {
     Ok(data)
 }
 
+/// Write a fixed-size block of binary data to stdout.
 pub fn write_to_stdout(data: &[u8]) -> Result<(), std::io::Error> {
     // Write data to stdout
     let mut stdout = io::stdout().lock();