typo: fix comments and docs into more sensible (bluealloy#1920)

* made base comment & doc typo fixes

* Updated one third of doc comments

* Revert "made base comment & doc typo fixes"

This reverts commit 65dad46.

* fixed outer doc comments, verbs and periods (passed 1 review)

* reverted few fixes

* fixed doctest failures

Author: lancorer

bins/revme/src/cmd.rs

@@ -12,7 +12,7 @@ use clap::Parser;
 pub enum MainCmd {
     /// Execute Ethereum state tests.
     Statetest(statetest::Cmd),
-    /// Execute eof validation tests.
+    /// Execute EOF validation tests.
     EofValidation(eofvalidation::Cmd),
     /// Run arbitrary EVM bytecode.
     Evm(evmrunner::Cmd),

bins/revme/src/cmd/bench.rs

@@ -13,15 +13,15 @@ pub enum BenchName {
     Transfer,
 }
 
-/// `bytecode` subcommand.
+/// `bytecode` subcommand
 #[derive(Parser, Debug)]
 pub struct Cmd {
     #[arg(value_enum)]
     name: BenchName,
 }
 
 impl Cmd {
-    /// Run bench command.
+    /// Runs bench command.
     pub fn run(&self) {
         match self.name {
             BenchName::Analysis => analysis::run(),

bins/revme/src/cmd/bench/analysis.rs

@@ -16,7 +16,7 @@ pub fn run() {
     let context = Context::builder()
         .with_db(BenchmarkDB::new_bytecode(bytecode))
         .modify_tx_chained(|tx| {
-            // execution globals block hash/gas_limit/coinbase/timestamp..
+            // Execution globals block hash/gas_limit/coinbase/timestamp..
             tx.caller = address!("1000000000000000000000000000000000000000");
             tx.transact_to = TxKind::Call(address!("0000000000000000000000000000000000000000"));
             //evm.env.tx.data = Bytes::from(hex::decode("30627b7c").unwrap());

bins/revme/src/cmd/bench/burntpix.rs

@@ -60,11 +60,11 @@ pub fn run() {
         _ => unreachable!("Execution failed: {:?}", tx_result),
     };
 
-    // remove returndata offset and length from output
+    // Remove returndata offset and length from output
     let returndata_offset = 64;
     let data = &return_data[returndata_offset..];
 
-    // remove trailing zeros
+    // Remove trailing zeros
     let trimmed_data = data
         .split_at(data.len() - data.iter().rev().filter(|&x| *x == 0).count())
         .0;

bins/revme/src/cmd/bench/snailtracer.rs

@@ -10,7 +10,7 @@ pub fn simple_example(bytecode: Bytecode) {
     let context = Context::builder()
         .with_db(BenchmarkDB::new_bytecode(bytecode.clone()))
         .modify_tx_chained(|tx| {
-            // execution globals block hash/gas_limit/coinbase/timestamp..
+            // Execution globals block hash/gas_limit/coinbase/timestamp..
             tx.caller = address!("1000000000000000000000000000000000000000");
             tx.transact_to = TxKind::Call(address!("0000000000000000000000000000000000000000"));
             tx.data = bytes!("30627b7c");

bins/revme/src/cmd/bench/transfer.rs

@@ -11,7 +11,7 @@ pub fn run() {
     let context = Context::builder()
         .with_db(BenchmarkDB::new_bytecode(Bytecode::new()))
         .modify_tx_chained(|tx| {
-            // execution globals block hash/gas_limit/coinbase/timestamp..
+            // Execution globals block hash/gas_limit/coinbase/timestamp..
             tx.caller = "0x0000000000000000000000000000000000000001"
                 .parse()
                 .unwrap();

bins/revme/src/cmd/bytecode.rs

@@ -15,9 +15,11 @@ pub struct Cmd {
     /// Is EOF code in RUNTIME mode.
     #[arg(long)]
     eof_runtime: bool,
-    /// Bytecode in hex format. If bytes start with 0xFE it will be interpreted as a EOF.
-    /// Otherwise, it will be interpreted as a EOF bytecode.
-    /// If not provided, it will operate in interactive EOF validation mode.
+    /// Bytecode in hex format string.
+    ///
+    /// - If bytes start with 0xFE it will be interpreted as a EOF.
+    /// - Otherwise, it will be interpreted as a EOF bytecode.
+    /// - If not provided, it will operate in interactive EOF validation mode.
     #[arg()]
     bytes: Option<String>,
 }
@@ -34,7 +36,7 @@ fn trim_decode(input: &str) -> Option<Bytes> {
 }
 
 impl Cmd {
-    /// Run statetest command.
+    /// Runs statetest command.
     pub fn run(&self) {
         let container_kind = if self.eof_initcode {
             Some(CodeType::ReturnContract)
@@ -64,12 +66,12 @@ impl Cmd {
             return;
         }
 
-        // else run command in loop.
+        // Else run command in loop.
         loop {
             let mut input = String::new();
             io::stdin().read_line(&mut input).expect("Input Error");
             if input.len() == 1 {
-                // just a newline, so exit
+                // Just a newline, so exit
                 return;
             }
             let Some(bytes) = trim_decode(&input) else {

bins/revme/src/cmd/eofvalidation.rs

@@ -8,18 +8,18 @@ use revm::bytecode::eof::{validate_raw_eof_inner, CodeType, EofError};
 use std::collections::BTreeMap;
 use std::path::{Path, PathBuf};
 
-/// `eof-validation` subcommand.
+/// `eof-validation` subcommand
 #[derive(Parser, Debug)]
 pub struct Cmd {
-    /// Input paths to EOF validation tests.
+    /// Input paths to EOF validation tests
     #[arg(required = true, num_args = 1..)]
     paths: Vec<PathBuf>,
 }
 
 impl Cmd {
-    /// Run statetest command.
+    /// Runs statetest command.
     pub fn run(&self) -> Result<(), Error> {
-        // check if path exists.
+        // Check if path exists.
         for path in &self.paths {
             if !path.exists() {
                 return Err(Error::Custom("The specified path does not exist"));
@@ -31,15 +31,15 @@ impl Cmd {
 }
 
 fn skip_test(name: &str) -> bool {
-    // embedded containers rules changed
+    // Embedded containers rules changed
     if name.starts_with("EOF1_embedded_container") {
         return true;
     }
     matches!(
         name,
         "EOF1_undefined_opcodes_186"
         | ""
-        // truncated data is only allowed in embedded containers
+        // Truncated data is only allowed in embedded containers
         | "validInvalid_48"
         | "validInvalid_1"
         | "EOF1_truncated_section_3"

bins/revme/src/cmd/evmrunner.rs

@@ -28,38 +28,40 @@ pub enum Errors {
     BytecodeDecodeError(#[from] BytecodeDecodeError),
 }
 
-/// Evm runner command allows running arbitrary evm bytecode.
-/// Bytecode can be provided from cli or from file with --path option.
+/// Evm runner command allows running arbitrary evm bytecode
+///
+/// Bytecode can be provided from cli or from file with `--path` option.
 #[derive(Parser, Debug)]
 pub struct Cmd {
-    /// Hex-encoded EVM bytecode to be executed.
+    /// Hex-encoded EVM bytecode to be executed
     #[arg(required_unless_present = "path")]
     bytecode: Option<String>,
-    /// Path to a file containing the hex-encoded EVM bytecode to be executed.
+    /// Path to a file containing the hex-encoded EVM bytecode to be executed
+    ///
     /// Overrides the positional `bytecode` argument.
     #[arg(long)]
     path: Option<PathBuf>,
-    /// Run in benchmarking mode.
+    /// Whether to run in benchmarking mode
     #[arg(long)]
     bench: bool,
-    /// Hex-encoded input/calldata bytes.
+    /// Hex-encoded input/calldata bytes
     #[arg(long, default_value = "")]
     input: String,
-    /// Print the state.
+    /// Whether to print the state
     #[arg(long)]
     state: bool,
-    /// Print the trace.
+    /// Whether to print the trace
     #[arg(long)]
     trace: bool,
 }
 
 impl Cmd {
-    /// Run evm runner command.
+    /// Runs evm runner command.
     pub fn run(&self) -> Result<(), Errors> {
         const CALLER: Address = address!("0000000000000000000000000000000000000001");
 
         let bytecode_str: Cow<'_, str> = if let Some(path) = &self.path {
-            // check if path exists.
+            // Check if path exists.
             if !path.exists() {
                 return Err(Errors::PathNotExists);
             }
@@ -80,7 +82,7 @@ impl Cmd {
         let nonce = db.basic(CALLER).unwrap().map_or(0, |account| account.nonce);
 
         // BenchmarkDB is dummy state that implements Database trait.
-        // the bytecode is deployed at zero address.
+        // The bytecode is deployed at zero address.
         let mut evm = MainEvm::new(
             Context::builder().with_db(db).modify_tx_chained(|tx| {
                 tx.caller = CALLER;

bins/revme/src/cmd/statetest.rs

@@ -8,33 +8,38 @@ use clap::Parser;
 use runner::{find_all_json_tests, run, TestError};
 use std::path::PathBuf;
 
-/// `statetest` subcommand.
+/// `statetest` subcommand
 #[derive(Parser, Debug)]
 pub struct Cmd {
-    /// Path to folder or file containing the tests. If multiple paths are specified
-    /// they will be run in sequence.
+    /// Path to folder or file containing the tests
+    ///
+    /// If multiple paths are specified they will be run in sequence.
     ///
     /// Folders will be searched recursively for files with the extension `.json`.
     #[clap(required = true, num_args = 1..)]
     paths: Vec<PathBuf>,
-    /// Run tests in a single thread.
+    /// Run tests in a single thread
     #[clap(short = 's', long)]
     single_thread: bool,
-    /// Output results in JSON format.
+    /// Output results in JSON format
+    ///
     /// It will stop second run of evm on failure.
     #[clap(long)]
     json: bool,
-    /// Output outcome in JSON format. If `--json` is true, this is implied.
+    /// Output outcome in JSON format
+    ///
+    /// If `--json` is true, this is implied.
+    ///
     /// It will stop second run of EVM on failure.
     #[clap(short = 'o', long)]
     json_outcome: bool,
-    /// Keep going after a test failure.
+    /// Keep going after a test failure
     #[clap(long, alias = "no-fail-fast")]
     keep_going: bool,
 }
 
 impl Cmd {
-    /// Run statetest command.
+    /// Runs `statetest` command.
     pub fn run(&self) -> Result<(), TestError> {
         for path in &self.paths {
             println!("\nRunning tests in {}...", path.display());