From d1907edd651439cd555bbdfab38003a4f2e479e1 Mon Sep 17 00:00:00 2001
From: Tyler <tyler.steele@protonmail.com>
Date: Sat, 24 Jul 2021 16:38:08 -0700
Subject: [PATCH] Adds additional words to exclude list. Improves documentation
 in dd.rs.

---
 src/uu/dd/src/dd.rs                           | 48 ++++++++++++++-----
 .../src/dd_unit_tests/block_unblock_tests.rs  |  2 +-
 .../dd/src/dd_unit_tests/conv_sync_tests.rs   |  2 +-
 .../dd/src/dd_unit_tests/conversion_tests.rs  |  2 +-
 src/uu/dd/src/dd_unit_tests/mod.rs            |  2 +-
 src/uu/dd/src/dd_unit_tests/sanity_tests.rs   |  2 +-
 src/uu/dd/src/parseargs/unit_tests.rs         |  2 +-
 tests/by-util/test_dd.rs                      |  2 +-
 8 files changed, 43 insertions(+), 19 deletions(-)

diff --git a/src/uu/dd/src/dd.rs b/src/uu/dd/src/dd.rs
index 6eef1350e..ef250c67c 100644
--- a/src/uu/dd/src/dd.rs
+++ b/src/uu/dd/src/dd.rs
@@ -5,6 +5,8 @@
 // For the full copyright and license information, please view the LICENSE
 // file that was distributed with this source code.
 
+// spell-checker:ignore fname, tname, fpath, specfile, testfile, unspec, ifile, ofile, outfile, fullblock, urand, fileio, atoe, atoibm, availible, behaviour, bmax, bremain, btotal, cflags, creat, ctable, ctty, datastructures, doesnt, etoa, fileout, fname, gnudd, iconvflags, nocache, noctty, noerror, nofollow, nolinks, nonblock, oconvflags, outfile, parseargs, rlen, rmax, rposition, rremain, rsofar, rstat, sigusr, sigval, wlen, wstat
+
 #[macro_use]
 extern crate uucore;
 use uucore::InvalidEncodingHandling;
@@ -41,7 +43,6 @@ use std::sync::{atomic::AtomicUsize, mpsc, Arc};
 use std::thread;
 use std::time;
 
-// const SYNTAX: &str = "dd [OPERAND]...\ndd OPTION";
 const ABOUT: &str = "copy, and optionally convert, a file system resource";
 const BUF_INIT_BYTE: u8 = 0xDD;
 const RTN_SUCCESS: i32 = 0;
@@ -428,6 +429,7 @@ impl Write for Output<io::Stdout> {
 }
 
 impl Output<io::Stdout> {
+    /// Write all data in the given buffer in writes of size obs.
     fn write_blocks(&mut self, buf: Vec<u8>) -> io::Result<WriteStat> {
         let mut writes_complete = 0;
         let mut writes_partial = 0;
@@ -455,6 +457,7 @@ impl Output<io::Stdout> {
 }
 
 impl Output<File> {
+    /// Write all data in the given buffer in writes of size obs.
     fn write_blocks(&mut self, buf: Vec<u8>) -> io::Result<WriteStat> {
         let mut writes_complete = 0;
         let mut writes_partial = 0;
@@ -483,6 +486,7 @@ impl Output<File> {
 
 /// Splits the content of buf into cbs-length blocks
 /// Appends padding as specified by conv=block and cbs=N
+/// Expects ascii encoded data
 fn block(buf: Vec<u8>, cbs: usize, rstat: &mut ReadStat) -> Vec<Vec<u8>> {
     let mut blocks = buf
         .split(|&e| e == b'\n')
@@ -508,6 +512,7 @@ fn block(buf: Vec<u8>, cbs: usize, rstat: &mut ReadStat) -> Vec<Vec<u8>> {
 
 /// Trims padding from each cbs-length partition of buf
 /// as specified by conv=unblock and cbs=N
+/// Expects ascii encoded data
 fn unblock(buf: Vec<u8>, cbs: usize) -> Vec<u8> {
     buf.chunks(cbs).fold(Vec::new(), |mut acc, block| {
         if let Some(last_char_idx) = block.iter().rposition(|&e| e != b' ') {
@@ -523,6 +528,13 @@ fn unblock(buf: Vec<u8>, cbs: usize) -> Vec<u8> {
     })
 }
 
+/// A helper for teasing out which options must be applied and in which order.
+/// Some user options, such as the presence of conversion tables, will determine whether the input is assumed to be ascii. The parser sets the Input::non_ascii flag accordingly.
+/// Examples:
+///     - If conv=ebcdic or conv=ibm is specified then block, unblock or swab must be performed before the conversion happens since the source will start in ascii.
+///     - If conv=ascii is specified then block, unblock or swab must be performed after the conversion since the source starts in ebcdic.
+///     - If no conversion is specified then the source is assumed to be in ascii.
+/// For more info see `info dd`
 fn conv_block_unblock_helper<R: Read>(
     mut buf: Vec<u8>,
     i: &mut Input<R>,
@@ -615,6 +627,7 @@ fn conv_block_unblock_helper<R: Read>(
     }
 }
 
+/// Read helper performs read operations common to all dd reads, and dispatches the buffer to relevent helper functions as dictated by the operations requested by the user.
 fn read_helper<R: Read>(
     i: &mut Input<R>,
     bsize: usize,
@@ -659,6 +672,9 @@ fn read_helper<R: Read>(
     }
 }
 
+// Print io lines of a status update:
+// <complete>+<partial> records in
+// <complete>+<partial> records out
 fn print_io_lines(update: &ProgUpdate) {
     eprintln!(
         "{}+{} records in",
@@ -672,6 +688,8 @@ fn print_io_lines(update: &ProgUpdate) {
         update.write_stat.writes_complete, update.write_stat.writes_partial
     );
 }
+// Print the progress line of a status update:
+// <byte-count> bytes (<base-1000-size>, <base-2-size>) copied, <time> s, <base-2-rate>/s
 fn make_prog_line(update: &ProgUpdate) -> String {
     let btotal_metric = Byte::from_bytes(update.write_stat.bytes_total)
         .get_appropriate_unit(false)
@@ -693,18 +711,24 @@ fn make_prog_line(update: &ProgUpdate) -> String {
         transfer_rate
     )
 }
+// Print progress line only. Overwrite the current line.
 fn reprint_prog_line(update: &ProgUpdate) {
     eprint!("\r{}", make_prog_line(update));
 }
+// Print progress line only. Print as a new line.
 fn print_prog_line(update: &ProgUpdate) {
     eprintln!("{}", make_prog_line(update));
 }
+// Print both io lines and progress line.
 fn print_transfer_stats(update: &ProgUpdate) {
     print_io_lines(update);
     print_prog_line(update);
 }
 
-/// Generate a progress updater that tracks progress, receives updates, and responds to progress update requests (signals).
+// Generate a progress updater that tracks progress, receives updates, and responds to progress update requests (signals).
+// Signals:
+// - SIGUSR1: Trigger progress line reprint. Linux (GNU & BSD) only.
+// - TODO: SIGINFO: Trigger progress line reprint. BSD-style Linux only.
 fn gen_prog_updater(rx: mpsc::Receiver<ProgUpdate>, print_level: Option<StatusLevel>) -> impl Fn() {
     // --------------------------------------------------------------
     #[cfg(target_os = "linux")]
@@ -753,20 +777,20 @@ fn gen_prog_updater(rx: mpsc::Receiver<ProgUpdate>, print_level: Option<StatusLe
     }
 }
 
-/// Calculate a 'good' internal buffer size.
-/// For performance of the read/write functions, the buffer should hold
-/// both an integral number of reads and an integral number of writes. For
-/// sane real-world memory use, it should not be too large. I believe
-/// the least common multiple is a good representation of these interests.
-/// https://en.wikipedia.org/wiki/Least_common_multiple#Using_the_greatest_common_divisor
+// Calculate a 'good' internal buffer size.
+// For performance of the read/write functions, the buffer should hold
+// both an integral number of reads and an integral number of writes. For
+// sane real-world memory use, it should not be too large. I believe
+// the least common multiple is a good representation of these interests.
+// https://en.wikipedia.org/wiki/Least_common_multiple#Using_the_greatest_common_divisor
 fn calc_bsize(ibs: usize, obs: usize) -> usize {
     let gcd = Gcd::gcd(ibs, obs);
     // calculate the lcm from gcd
     (ibs / gcd) * obs
 }
 
-/// Calculate the buffer size appropriate for this loop iteration, respecting
-/// a count=N if present.
+// Calculate the buffer size appropriate for this loop iteration, respecting
+// a count=N if present.
 fn calc_loop_bsize(
     count: &Option<CountType>,
     rstat: &ReadStat,
@@ -790,8 +814,8 @@ fn calc_loop_bsize(
     }
 }
 
-/// Decide if the current progress is below a count=N limit or return
-/// true if no such limit is set.
+// Decide if the current progress is below a count=N limit or return
+// true if no such limit is set.
 fn below_count_limit(count: &Option<CountType>, rstat: &ReadStat, wstat: &WriteStat) -> bool {
     match count {
         Some(CountType::Reads(n)) => {
diff --git a/src/uu/dd/src/dd_unit_tests/block_unblock_tests.rs b/src/uu/dd/src/dd_unit_tests/block_unblock_tests.rs
index 35dda92eb..5ed15e876 100644
--- a/src/uu/dd/src/dd_unit_tests/block_unblock_tests.rs
+++ b/src/uu/dd/src/dd_unit_tests/block_unblock_tests.rs
@@ -1,4 +1,4 @@
-// spell-checker:ignore fname, tname, fpath, specfile, testfile, unspec, ifile, ofile, outfile, fullblock, urand, fileio
+// spell-checker:ignore fname, tname, fpath, specfile, testfile, unspec, ifile, ofile, outfile, fullblock, urand, fileio, atoe, atoibm, availible, behaviour, bmax, bremain, btotal, cflags, creat, ctable, ctty, datastructures, doesnt, etoa, fileout, fname, gnudd, iconvflags, nocache, noctty, noerror, nofollow, nolinks, nonblock, oconvflags, outfile, parseargs, rlen, rmax, rposition, rremain, rsofar, rstat, sigusr, sigval, wlen, wstat
 
 use super::*;
 
diff --git a/src/uu/dd/src/dd_unit_tests/conv_sync_tests.rs b/src/uu/dd/src/dd_unit_tests/conv_sync_tests.rs
index 7d7c7d879..63dd1404c 100644
--- a/src/uu/dd/src/dd_unit_tests/conv_sync_tests.rs
+++ b/src/uu/dd/src/dd_unit_tests/conv_sync_tests.rs
@@ -1,4 +1,4 @@
-// spell-checker:ignore fname, tname, fpath, specfile, testfile, unspec, ifile, ofile, outfile, fullblock, urand, fileio
+// spell-checker:ignore fname, tname, fpath, specfile, testfile, unspec, ifile, ofile, outfile, fullblock, urand, fileio, atoe, atoibm, availible, behaviour, bmax, bremain, btotal, cflags, creat, ctable, ctty, datastructures, doesnt, etoa, fileout, fname, gnudd, iconvflags, nocache, noctty, noerror, nofollow, nolinks, nonblock, oconvflags, outfile, parseargs, rlen, rmax, rposition, rremain, rsofar, rstat, sigusr, sigval, wlen, wstat
 
 use super::*;
 
diff --git a/src/uu/dd/src/dd_unit_tests/conversion_tests.rs b/src/uu/dd/src/dd_unit_tests/conversion_tests.rs
index 163d77e7e..1c9c31013 100644
--- a/src/uu/dd/src/dd_unit_tests/conversion_tests.rs
+++ b/src/uu/dd/src/dd_unit_tests/conversion_tests.rs
@@ -1,4 +1,4 @@
-// spell-checker:ignore fname, tname, fpath, specfile, testfile, unspec, ifile, ofile, outfile, fullblock, urand, fileio
+// spell-checker:ignore fname, tname, fpath, specfile, testfile, unspec, ifile, ofile, outfile, fullblock, urand, fileio, atoe, atoibm, availible, behaviour, bmax, bremain, btotal, cflags, creat, ctable, ctty, datastructures, doesnt, etoa, fileout, fname, gnudd, iconvflags, nocache, noctty, noerror, nofollow, nolinks, nonblock, oconvflags, outfile, parseargs, rlen, rmax, rposition, rremain, rsofar, rstat, sigusr, sigval, wlen, wstat
 
 use super::*;
 
diff --git a/src/uu/dd/src/dd_unit_tests/mod.rs b/src/uu/dd/src/dd_unit_tests/mod.rs
index f3f0858e7..e802c4534 100644
--- a/src/uu/dd/src/dd_unit_tests/mod.rs
+++ b/src/uu/dd/src/dd_unit_tests/mod.rs
@@ -1,4 +1,4 @@
-// spell-checker:ignore fname, tname, fpath, specfile, testfile, unspec, ifile, ofile, outfile, fullblock, urand, fileio
+// spell-checker:ignore fname, tname, fpath, specfile, testfile, unspec, ifile, ofile, outfile, fullblock, urand, fileio, atoe, atoibm, availible, behaviour, bmax, bremain, btotal, cflags, creat, ctable, ctty, datastructures, doesnt, etoa, fileout, fname, gnudd, iconvflags, nocache, noctty, noerror, nofollow, nolinks, nonblock, oconvflags, outfile, parseargs, rlen, rmax, rposition, rremain, rsofar, rstat, sigusr, sigval, wlen, wstat
 
 use super::*;
 
diff --git a/src/uu/dd/src/dd_unit_tests/sanity_tests.rs b/src/uu/dd/src/dd_unit_tests/sanity_tests.rs
index 9d1c126b0..efb542eb5 100644
--- a/src/uu/dd/src/dd_unit_tests/sanity_tests.rs
+++ b/src/uu/dd/src/dd_unit_tests/sanity_tests.rs
@@ -1,4 +1,4 @@
-// spell-checker:ignore fname, tname, fpath, specfile, testfile, unspec, ifile, ofile, outfile, fullblock, urand, fileio
+// spell-checker:ignore fname, tname, fpath, specfile, testfile, unspec, ifile, ofile, outfile, fullblock, urand, fileio, atoe, atoibm, availible, behaviour, bmax, bremain, btotal, cflags, creat, ctable, ctty, datastructures, doesnt, etoa, fileout, fname, gnudd, iconvflags, nocache, noctty, noerror, nofollow, nolinks, nonblock, oconvflags, outfile, parseargs, rlen, rmax, rposition, rremain, rsofar, rstat, sigusr, sigval, wlen, wstat
 
 use super::*;
 
diff --git a/src/uu/dd/src/parseargs/unit_tests.rs b/src/uu/dd/src/parseargs/unit_tests.rs
index 35dcdf8e0..f8cdef4e9 100644
--- a/src/uu/dd/src/parseargs/unit_tests.rs
+++ b/src/uu/dd/src/parseargs/unit_tests.rs
@@ -1,4 +1,4 @@
-// spell-checker:ignore fname, tname, fpath, specfile, testfile, unspec, ifile, ofile, outfile, fullblock, urand, fileio
+// spell-checker:ignore fname, tname, fpath, specfile, testfile, unspec, ifile, ofile, outfile, fullblock, urand, fileio, atoe, atoibm, availible, behaviour, bmax, bremain, btotal, cflags, creat, ctable, ctty, datastructures, doesnt, etoa, fileout, fname, gnudd, iconvflags, nocache, noctty, noerror, nofollow, nolinks, nonblock, oconvflags, outfile, parseargs, rlen, rmax, rposition, rremain, rsofar, rstat, sigusr, sigval, wlen, wstat
 
 use super::*;
 
diff --git a/tests/by-util/test_dd.rs b/tests/by-util/test_dd.rs
index 821e9f0c3..f48f454f7 100644
--- a/tests/by-util/test_dd.rs
+++ b/tests/by-util/test_dd.rs
@@ -1,4 +1,4 @@
-// spell-checker:ignore fname, tname, fpath, specfile, testfile, unspec, ifile, ofile, outfile, fullblock, urand, fileio
+// spell-checker:ignore fname, tname, fpath, specfile, testfile, unspec, ifile, ofile, outfile, fullblock, urand, fileio, atoe, atoibm, availible, behaviour, bmax, bremain, btotal, cflags, creat, ctable, ctty, datastructures, doesnt, etoa, fileout, fname, gnudd, iconvflags, nocache, noctty, noerror, nofollow, nolinks, nonblock, oconvflags, outfile, parseargs, rlen, rmax, rposition, rremain, rsofar, rstat, sigusr, sigval, wlen, wstat
 
 use crate::common::util::*;