Add typos + cargo doc CI (#32)

* ci: add separate `typo` job

* add `typos.toml` for false positives

* fix all typos

* ci: add `cargo doc` step

* fix doc errors

* contributing.md: update passing CI steps

* fix more typos, add exception to `cryptonight/`

* ci: move `cargo doc` step within `ci` job

It needs dependencies.

* ci: add https://github.com/Cuprate/cuprate/pull/63

* test-utils: fix typo

* ci: switch `rustup update` and switch order

* ci: only update rust on unix

* ci: set `RUSTDOCFLAGS` env earlier

* ci: only run `cargo doc` on linux

* ci: remove `bash` on `cargo doc`

* ci: remove `--all-targets`

We now have the target OS's in CI, no need to compile for each.

* contributing.md: update ci steps

* ci: add `--all-targets` back to clippy, build

* update contributing.md

.github/workflows/ci.yml

@@ -13,16 +13,18 @@ env:
   RUST_BACKTRACE: "full"
   # Increase thread stack size to 8 megabytes.
   RUST_MIN_STACK: 8000000
+  # Fail on documentation warnings.
+  RUSTDOCFLAGS: '-D warnings'
 
 jobs:
   # Run format separately.
+  #
+  # This will fast-cancel other CI early if this fails.
+  #
+  # `cargo fmt` checks _all_ code, regardless of the OS
+  # or any `#[cfg]`'s, so this only needs to run on Linux.
   fmt:
-    runs-on: ${{ matrix.os }}
-
-    strategy:
-      matrix:
-        os: [windows-latest, macos-latest, ubuntu-latest]
-
+    runs-on: ubuntu-latest
     steps:
     - name: Checkout
       uses: actions/checkout@v4
@@ -31,6 +33,16 @@ jobs:
     - name: Format
       run: cargo fmt --all --check
 
+  # Run typo checker separately.
+  # This will fast-cancel other CI early if this fails.
+  typo:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+    - name: Spell Check
+      uses: crate-ci/typos@master
+
   # All other CI.
   ci:
     runs-on: ${{ matrix.os }}
@@ -84,19 +96,23 @@ jobs:
         update: true
         install: mingw-w64-x86_64-toolchain mingw-w64-x86_64-boost msys2-runtime-devel git mingw-w64-x86_64-cmake mingw-w64-x86_64-ninja
 
+    - name: Update Rust (UNIX)
+      if: matrix.os != 'windows-latest'
+      run: rustup update
+
     - name: Switch target (Windows)
       if: matrix.os == 'windows-latest'
       run: rustup toolchain install stable-x86_64-pc-windows-gnu -c clippy && rustup set default-host x86_64-pc-windows-gnu && rustup default stable-x86_64-pc-windows-gnu
 
-    - name: Update Rust
-      run: rustup update
+    - name: Documentation
+      run: cargo doc --workspace --all-features
 
     - name: Clippy (fail on warnings)
-      run: cargo clippy --workspace --all-targets --all-features -- -D warnings
+      run: cargo clippy --workspace --all-features --all-targets -- -D warnings
 
     - name: Test
-      run: cargo test --all-features --workspace --all-targets
+      run: cargo test --all-features --workspace
 
     # TODO: upload binaries with `actions/upload-artifact@v3`
     - name: Build
-      run: cargo build --all-features --all-targets --workspace
+      run: cargo build --all-features --all-targets --workspace

CONTRIBUTING.md

@@ -14,13 +14,21 @@ When you are at a stage where you would like feedback you can open a draft PR, k
 Once your PR is at the stage where you feel it's ready to go, open it for review.
 
 ## Passing CI
+The first 3 steps to CI are formatting, typo, and documentation checking.
 
-To pass CI make sure all these successfully run:
+Check if your changes are formatted, typo-free, and documented correctly by running:
+- `cargo fmt --all --check`
+- `typos`
+- `RUSTDOCFLAGS='-D warnings' cargo doc --workspace --all-features`
 
-- `cargo clippy --workspace --all-targets --all-features -- -D warnings`
+`typos` can be installed with `cargo` from: https://github.com/crate-ci/typos.
+
+After that, ensure all lints, tests, and builds are successful by running:
+
+- `cargo clippy --workspace --all-features --all-targets -- -D warnings`
 - `cargo fmt --all`
-- `cargo test`
-- `cargo build`
+- `cargo test --all-features --workspace`
+- `cargo build --all-features --all-targets --workspace`
 
 ## Coding guidelines
 

consensus/Cargo.toml

@@ -2,7 +2,7 @@
 name = "cuprate-consensus"
 version = "0.1.0"
 edition = "2021"
-description = "A crate implimenting all Moneros consensus rules."
+description = "A crate implementing all Moneros consensus rules."
 license = "MIT"
 authors = ["Boog900"]
 repository = "https://github.com/Cuprate/cuprate/tree/main/consensus"

consensus/src/batch_verifier.rs

@@ -41,7 +41,7 @@ impl MultiThreadedBatchVerifier {
             .into_iter()
             .map(UnsafeCell::into_inner)
             .par_bridge()
-            .find_any(|batch_verifer| !batch_verifer.verify_vartime())
+            .find_any(|batch_verifier| !batch_verifier.verify_vartime())
             .is_none()
     }
 }

consensus/src/bin/scan_chain.rs

@@ -213,7 +213,7 @@ mod bin {
         #[arg(short, long, default_value = "mainnet")]
         network: String,
         /// A list of RPC nodes we should use.
-        /// Example: http://xmr-node.cakewallet.com:18081
+        /// Example: <http://xmr-node.cakewallet.com:18081>
         #[arg(long)]
         rpc_nodes: Vec<String>,
         /// Stops the scanner from including the default list of nodes, this is not

consensus/src/context/rx_vms.rs

@@ -165,7 +165,7 @@ pub(crate) fn get_last_rx_seed_heights(mut last_height: u64, mut amount: usize)
             return seeds;
         }
 
-        // We don't include the lag as we only want seeds not the specific seed fo this height.
+        // We don't include the lag as we only want seeds not the specific seed for this height.
         let seed_height = (last_height - 1) & !(RX_SEEDHASH_EPOCH_BLOCKS - 1);
         seeds.push(seed_height);
         last_height = seed_height

consensus/src/tests/context/difficulty.rs

@@ -144,7 +144,7 @@ proptest! {
     }
 
     #[test]
-    fn next_difficulty_consistant(diff_cache in arb_difficulty_cache(TEST_TOTAL_ACCOUNTED_BLOCKS), hf in any::<HardFork>()) {
+    fn next_difficulty_consistent(diff_cache in arb_difficulty_cache(TEST_TOTAL_ACCOUNTED_BLOCKS), hf in any::<HardFork>()) {
         let first_call = diff_cache.next_difficulty(&hf);
         prop_assert_eq!(first_call, diff_cache.next_difficulty(&hf));
         prop_assert_eq!(first_call, diff_cache.next_difficulty(&hf));

consensus/src/transactions/contextual_data.rs

@@ -107,7 +107,7 @@ pub async fn batch_refresh_ring_member_info<'a, D: Database + Clone + Send + Syn
     Ok(())
 }
 
-/// This function returns the transaction verification datas that need refreshing.
+/// This function returns the transaction verification data that need refreshing.
 ///
 /// The first returned vec needs a full refresh.
 /// The second returned vec only needs a partial refresh.

cryptonight/c/skein_port.h

@@ -76,7 +76,7 @@
                                 multiple of size / 8)
 
     ptr_cast(x,size)            casts a pointer to a pointer to a 
-                                varaiable of length 'size' bits
+                                variable of length 'size' bits
 */
 
 #define ui_type(size)               uint##size##_t

cryptonight/c/slow-hash.c

@@ -1454,7 +1454,7 @@ void cn_slow_hash(const void *data, size_t length, char *hash, int variant, int
 }
 #else /* aarch64 && crypto */
 
-// ND: Some minor optimizations for ARMv7 (raspberrry pi 2), effect seems to be ~40-50% faster.
+// ND: Some minor optimizations for ARMv7 (raspberry pi 2), effect seems to be ~40-50% faster.
 //     Needs more work.
 
 #ifdef NO_OPTIMIZED_MULTIPLY_ON_ARM

net/epee-encoding/README.md

@@ -146,7 +146,7 @@ example:
 #[derive(EpeeObject)]
 pub struct HandshakeR {
     #[epee_alt_name("node_data")]
-    pub node_daa: BasicNodeData,
+    pub node_data: BasicNodeData,
 }
 ```
 

net/epee-encoding/src/lib.rs

@@ -217,7 +217,7 @@ fn read_object<T: EpeeObject, B: Buf>(r: &mut B, skipped_objects: &mut u8) -> Re
     object_builder.finish()
 }
 
-/// Read a marker from the [`Read`], this function should only be used for
+/// Read a marker from the [`Buf`], this function should only be used for
 /// custom serialisation based on the marker otherwise just use [`read_epee_value`].
 pub fn read_marker<B: Buf>(r: &mut B) -> Result<Marker> {
     Marker::try_from(checked_read_primitive(r, Buf::get_u8)?)

net/epee-encoding/tests/stack_overflow.rs

@@ -20,7 +20,7 @@ epee_object!(
 );
 
 #[test]
-fn stack_overlfow() {
+fn stack_overflow() {
     let bytes = vec![
         1, 17, 1, 1, 1, 1, 2, 1, 1, 8, 3, 114, 101, 113, 8, 3, 1, 100, 12, 8, 3, 118, 97, 108, 8,
         7, 1, 100, 12, 8, 3, 118, 97, 108, 8, 7, 1, 100, 12, 8, 3, 118, 97, 108, 8, 7, 1, 100, 12,

net/fixed-bytes/src/lib.rs

@@ -39,7 +39,7 @@ impl Debug for FixedByteError {
 
 /// A fixed size byte slice.
 ///
-/// Internally this is just a wrapper around [`Bytes`], with the constructors checking that the length is equal to [`N`].
+/// Internally this is just a wrapper around [`Bytes`], with the constructors checking that the length is equal to `N`.
 /// This implements [`Deref`] with the target being `[u8; N]`.
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub struct ByteArray<const N: usize>(Bytes);

old_database/src/interface.rs

@@ -194,7 +194,7 @@ impl<'service, D: Database<'service>> Interface<'service, D> {
 
         cursor_blockmetadata.del()?;
 
-        // Then we delete all its revelent txs
+        // Then we delete all its relevant txs
         for tx_hash in blk.tx_hashes.iter() {
             // 1 more condition in monerod TODO:
             self.remove_transaction(*tx_hash)?;
@@ -684,9 +684,9 @@ impl<'service, D: Database<'service>> Interface<'service, D> {
     /// `get_tx_list` fetches the transactions with given hashes.
     ///
     /// Should return a vector with the requested transactions. In case of failures, a DB_FAILURES will be return.
-    /// Precisly, a HASH_DNE error will be returned with the correspondig hash of transaction that is not found in the DB.
+    /// Precisely, a HASH_DNE error will be returned with the corresponding hash of transaction that is not found in the DB.
     ///
-    /// `hlist`: is the given collection of hashes correspondig to the transactions to fetch.
+    /// `hlist`: is the given collection of hashes corresponding to the transactions to fetch.
     fn get_tx_list(
         &'service self,
         hash_list: Vec<Hash>,

old_database/src/lib.rs

@@ -20,7 +20,7 @@
 //! At the moment, the only storage engine available is MDBX.
 //! The next storage engine planned is HSE (Heteregeonous Storage Engine) from Micron.
 //!
-//! For more informations, please consult this docs:
+//! For more information, please consult this docs:
 
 #![deny(unused_attributes)]
 #![forbid(unsafe_code)]
@@ -54,7 +54,7 @@ const BINCODE_CONFIG: bincode::config::Configuration<
 
 pub mod database {
     //! This module contains the Database abstraction trait. Any key/value storage engine implemented need
-    //! to fullfil these associated types and functions, in order to be usable. This module also contains the
+    //! to fulfil these associated types and functions, in order to be usable. This module also contains the
     //! Interface struct which is used by the DB Reactor to interact with the database.
 
     use crate::{

old_database/src/table.rs

@@ -137,7 +137,7 @@ impl_duptable!(
 );
 
 impl_duptable!(
-    /// `txsidentifier` is a table defining a relation between the hash of a transaction and its transaction Indexes. Its primarly used to quickly find tx's ID by its hash.
+    /// `txsidentifier` is a table defining a relation between the hash of a transaction and its transaction Indexes. Its primarily used to quickly find tx's ID by its hash.
     txsidentifier,
     Compat<Hash>,
     (),

old_database/src/types.rs

@@ -37,7 +37,7 @@ pub struct BlockMetadata {
 }
 
 #[derive(Clone, Debug, Encode, Decode)]
-/// [`AltBlock`] is a struct contaning an alternative `block` (defining an alternative mainchain) and its metadata (`block_height`, `cumulative_weight`,
+/// [`AltBlock`] is a struct containing an alternative `block` (defining an alternative mainchain) and its metadata (`block_height`, `cumulative_weight`,
 /// `cumulative_difficulty_low`, `cumulative_difficulty_high`, `already_generated_coins`).
 /// This struct is used in [`crate::table::altblock`] table.
 pub struct AltBlock {
@@ -317,7 +317,7 @@ pub struct OutputMetadata {
 //#[derive(Clone, Debug, Encode, Decode)]
 //// [`OutAmountIdx`] is a struct tuple used to contain the two keys used in [`crate::table::outputamounts`] table.
 //// In monerod, the database key is the amount while the *cursor key* (the amount index) is the prefix of the actual data being returned.
-//// As we prefere to note use cursor with partial data, we prefer to concat these two into a unique key
+//// As we prefer to note use cursor with partial data, we prefer to concat these two into a unique key
 //pub struct OutAmountIdx(u64,u64);
 // MAYBE NOT FINALLY
 

p2p/monero-p2p/src/client.rs

@@ -15,11 +15,11 @@ use crate::{
     handles::ConnectionHandle, NetworkZone, PeerError, PeerRequest, PeerResponse, SharedError,
 };
 
-mod conector;
 mod connection;
+mod connector;
 pub mod handshaker;
 
-pub use conector::{ConnectRequest, Connector};
+pub use connector::{ConnectRequest, Connector};
 pub use handshaker::{DoHandshakeRequest, HandShaker, HandshakeError};
 
 /// An internal identifier for a given peer, will be their address if known

p2p/monero-p2p/src/client/connection.rs

@@ -161,7 +161,7 @@ where
         tracing::debug!("waiting for peer/client request.");
         tokio::select! {
             biased;
-            bradcast_req = self.broadcast_rx.next() => {
+            broadcast_req = self.broadcast_rx.next() => {
                 todo!()
             }
             client_req = self.client_rx.next() => {
@@ -188,7 +188,7 @@ where
         tracing::debug!("waiting for peer response..");
         tokio::select! {
             biased;
-            bradcast_req = self.broadcast_rx.next() => {
+            broadcast_req = self.broadcast_rx.next() => {
                 todo!()
             }
             peer_message = stream.next() => {

p2p/monero-p2p/src/client/handshaker.rs

@@ -418,7 +418,7 @@ async fn wait_for_message<Z: NetworkZone>(
                 eager_protocol_messages.push(protocol_message);
                 if eager_protocol_messages.len() > MAX_EAGER_PROTOCOL_MESSAGES {
                     tracing::debug!(
-                        "Peer sent too many protocl messages before a handshake response."
+                        "Peer sent too many protocol messages before a handshake response."
                     );
                     return Err(HandshakeError::PeerSentInvalidMessage(
                         "Peer sent too many protocol messages",

test-utils/src/monerod.rs

@@ -39,14 +39,14 @@ pub async fn monerod(flags: Vec<String>, mutable: bool) -> (SocketAddr, SocketAd
 
     // We only actually need these channels on first run so this might be wasteful
     let (tx, rx) = mpsc::channel(3);
-    let mut should_spwan = false;
+    let mut should_spawn = false;
 
     let monero_handler_tx = MONEROD_HANDLER_CHANNEL.get_or_init(|| {
-        should_spwan = true;
+        should_spawn = true;
         tx
     });
 
-    if should_spwan {
+    if should_spawn {
         // If this call was the first call to start a monerod instance then start the handler.
         let manager = MoneroDManager::new().await;
         tokio::task::spawn(manager.run(rx));
@@ -73,7 +73,7 @@ struct MoneroDRequest {
 }
 
 /// A struct representing a spawned monerod.
-struct SpwanedMoneroD {
+struct SpawnedMoneroD {
     /// A marker for if the test that spawned this monerod is going to mutate it.
     mutable: bool,
     /// A handle to the monerod process, monerod will be stopped when this is dropped.
@@ -88,7 +88,7 @@ struct SpwanedMoneroD {
 /// A manger of spawned monerods.
 struct MoneroDManager {
     /// A map of start flags to monerods.
-    monerods: HashMap<Vec<String>, Vec<SpwanedMoneroD>>,
+    monerods: HashMap<Vec<String>, Vec<SpawnedMoneroD>>,
     /// The path to the monerod binary.
     path_to_monerod: PathBuf,
 }
@@ -116,7 +116,7 @@ impl MoneroDManager {
         }
     }
 
-    /// Trys to get a current monerod instance or spans one if there is not an appropriate one to use.
+    /// Tries to get a current monerod instance or spans one if there is not an appropriate one to use.
     /// Returns the p2p port and then the RPC port of the spawned monerd.
     fn get_monerod_with_flags(&mut self, flags: Vec<String>, mutable: bool) -> (u16, u16) {
         // If we need to mutate monerod's blockchain then we can't reuse one.
@@ -147,7 +147,7 @@ impl MoneroDManager {
             .spawn()
             .unwrap();
 
-        let spawned_monerd = SpwanedMoneroD {
+        let spawned_monerod = SpawnedMoneroD {
             mutable,
             process: monerod,
             rpc_port,
@@ -157,7 +157,7 @@ impl MoneroDManager {
         self.monerods
             .entry(flags.clone())
             .or_default()
-            .push(spawned_monerd);
+            .push(spawned_monerod);
         let Some(monerods) = self.monerods.get(&flags) else {
             unreachable!()
         };

typos.toml

@@ -0,0 +1,16 @@
+[default]
+# False positive patterns.
+extend-ignore-identifiers-re = [
+	"ND",
+	"DNE",
+	# in file: `/cryptonight/c/oaes_lib.c:1213`
+	# not sure if false-positive or not.
+	"InvMixColums",
+]
+
+[files]
+# False positive files.
+extend-exclude = [
+	"/misc/gpg_keys/",
+	"cryptonight/",
+]