Merge pull request #69 from semiotic-ai/joseph/back-170-enforce-docum…

…entation-of-public-methods-in-header

chore(accumulator): enforce documentation of all pub methods

crates/header-accumulator/src/epoch.rs

@@ -93,10 +93,12 @@ impl From<Epoch> for EpochAccumulator {
 }
 
 impl Epoch {
+    /// Get the epoch number
     pub fn number(&self) -> usize {
         self.number
     }
 
+    /// Get an iterator over the epoch data
     pub fn iter(&self) -> std::slice::Iter<'_, HeaderRecord> {
         self.data.iter()
     }

crates/header-accumulator/src/errors.rs

@@ -7,47 +7,77 @@ use firehose_protos::ProtosError;
 /// Possible errors while interacting with the lib
 #[derive(thiserror::Error, Debug)]
 pub enum EraValidateError {
+    /// Error decoding header from flat files
     #[error("Error decoding header from flat files")]
     HeaderDecodeError,
+
+    /// Era accumulator mismatch
     #[error("Era accumulator mismatch")]
     EraAccumulatorMismatch,
 
+    /// Block epoch mismatch
     #[error("Block epoch {block_epoch} (block number {block_number}) could not be proven with provided epoch {epoch_number}.")]
     EpochNotMatchForHeader {
+        /// Epoch number
         epoch_number: usize,
+        /// Block number
         block_number: u64,
+        /// Block epoch
         block_epoch: usize,
     },
 
+    /// Epoch not found in provided list
     #[error("Expected epoch {block_epoch} was not found in the provided epoch list. Epochs provided: {epoch_list:?}.")]
     EpochNotFoundInProvidedList {
+        /// Block epoch
         block_epoch: usize,
+        /// Provided epoch list
         epoch_list: Vec<usize>,
     },
 
+    /// Error generating inclusion proof
     #[error("Error generating inclusion proof")]
     ProofGenerationFailure,
+
+    /// Error validating inclusion proof
     #[error("Error validating inclusion proof")]
     ProofValidationFailure,
 
+    /// Invalid epoch length
     #[error("Blocks in epoch must be exactly 8192 units, found {0}")]
     InvalidEpochLength(usize),
 
+    /// Missing block in epoch
     #[error("Block was missing while creating epoch {epoch}. Missing blocks: {blocks:?}")]
-    MissingBlock { epoch: u64, blocks: Vec<u64> },
+    MissingBlock {
+        /// Epoch number
+        epoch: u64,
+        /// Missing blocks
+        blocks: Vec<u64>,
+    },
 
+    /// Invalid block in epoch
     #[error("Not all blocks are in the same epoch. Epochs found: {0:?}")]
     InvalidBlockInEpoch(HashSet<u64>),
+
+    /// Error converting ExtHeaderRecord to header block number
     #[error("Error converting ExtHeaderRecord to header block number {0}")]
     ExtHeaderRecordError(u64),
+
+    /// Invalid block range
     #[error("Invalid block range: {0} - {1}")]
     InvalidBlockRange(u64, u64),
+
+    /// Epoch is in post merge
     #[error("Epoch is in post merge: {0}")]
     EpochPostMerge(usize),
 
+    /// Header block number is different than expected
     #[error("Header block number ({block_number}) is different than expected ({expected_number})")]
     HeaderMismatch {
+        /// Expected block number
         expected_number: u64,
+        /// Actual block number
         block_number: u64,
     },
 }

crates/header-accumulator/src/lib.rs

@@ -7,6 +7,8 @@
 //! against header accumulators. This process is used to verify the
 //! authenticity of these blocks.
 
+#![deny(missing_docs)]
+
 mod epoch;
 mod era_validator;
 mod errors;

crates/header-accumulator/src/types.rs

@@ -14,9 +14,13 @@ use crate::errors::EraValidateError;
 /// You can extract the full header as an option
 #[derive(Clone)]
 pub struct ExtHeaderRecord {
+    /// Block hash
     pub block_hash: B256,
+    /// Total difficulty
     pub total_difficulty: Uint<256, 4>,
+    /// Block number
     pub block_number: u64,
+    /// Full header
     pub full_header: Option<Header>,
 }