clean up code comments

Author: dspicher

src/lib.rs

@@ -35,15 +35,10 @@ impl std::fmt::Display for BlockHeightRange {
     }
 }
 
-/// Holds all available user arguments
 pub struct ParserOptions {
-    // Holds the relevant coin parameters we need for parsing
     pub coin: CoinType,
-    // Enable this if you want to check the chain index integrity and merkle root for each block.
     pub verify: bool,
-    // Path to directory where blk.dat files are stored
     pub blockchain_dir: std::path::PathBuf,
-    // Range which is considered for parsing
     pub range: BlockHeightRange,
 }
 
@@ -52,7 +47,6 @@ pub fn command() -> Command {
     let coins = ["bitcoin", "testnet3"];
     Command::new("bitcoin-blockparser")
     .version(clap::crate_version!())
-    // Add flags
     .arg(Arg::new("verify")
         .long("verify")
         .action(clap::ArgAction::SetTrue)
@@ -62,7 +56,6 @@ pub fn command() -> Command {
         .short('v')
         .action(clap::ArgAction::Count)
         .help("Increases verbosity level. Info=0, Debug=1, Trace=2 (default: 0)"))
-    // Add options
     .arg(Arg::new("coin")
         .short('c')
         .long("coin")
@@ -87,14 +80,12 @@ pub fn command() -> Command {
         .help("Specify last block for parsing (inclusive) (default: all known blocks)"))
 }
 
-/// Returns default directory. TODO: test on windows
 fn get_absolute_blockchain_dir(coin: &CoinType) -> std::path::PathBuf {
     dirs::home_dir()
         .expect("Unable to get home path from env!")
         .join(&coin.default_folder)
 }
 
-/// Parses args or panics if some requirements are not met.
 pub fn parse_args(matches: &clap::ArgMatches) -> anyhow::Result<ParserOptions> {
     let verify = matches.get_flag("verify");
 

src/main.rs

@@ -20,7 +20,6 @@ fn main() {
             }
         };
 
-    // Apply log filter based on verbosity
     tracing::info!(target: "main", "Starting bitcoin-blockparser v{} ...", env!("CARGO_PKG_VERSION"));
     if options.verify {
         tracing::info!(target: "main", "Configured to verify merkle roots and block hashes");

src/parser/blkfile.rs

@@ -7,7 +7,6 @@ use anyhow::Context;
 
 use crate::parser::reader::BlockchainRead;
 
-/// Holds all necessary data about a raw blk file
 #[derive(Debug)]
 pub struct BlkFile {
     pub path: PathBuf,
@@ -24,7 +23,6 @@ impl BlkFile {
         }
     }
 
-    /// Opens the file handle (does nothing if the file has been opened already)
     fn open(&mut self) -> anyhow::Result<&mut std::io::BufReader<File>> {
         if self.reader.is_none() {
             tracing::debug!(target: "blkfile", "Opening {} ...", &self.path.display());
@@ -33,7 +31,6 @@ impl BlkFile {
         Ok(self.reader.as_mut().unwrap())
     }
 
-    /// Closes the file handle
     pub fn close(&mut self) {
         tracing::debug!(target: "blkfile", "Closing {} ...", &self.path.display());
         if self.reader.is_some() {
@@ -56,7 +53,6 @@ impl BlkFile {
         reader.read_block()
     }
 
-    /// Collects all blk*.dat paths in the given directory
     pub fn from_path(path: &Path) -> anyhow::Result<HashMap<u64, BlkFile>> {
         tracing::info!(target: "blkfile", "Reading files from {} ...", path.display());
         let mut collected = HashMap::with_capacity(4000);
@@ -76,9 +72,7 @@ impl BlkFile {
                             .to_str()
                             .context("invalid path")?,
                     );
-                    // Check if it's a valid blk file
                     if let Some(index) = BlkFile::parse_blk_index(&file_name, "blk", ".dat") {
-                        // Build BlkFile structures
                         let size = std::fs::metadata(path.as_path())?.len();
                         tracing::trace!(target: "blkfile", "Adding {} ... (index: {}, size: {})", path.display(), index, size);
                         collected.insert(index, BlkFile::new(path, size));
@@ -98,8 +92,6 @@ impl BlkFile {
         }
     }
 
-    /// Resolves a PathBuf for the given entry.
-    /// Also resolves symlinks if present.
     fn resolve_path(entry: &DirEntry) -> std::io::Result<PathBuf> {
         if entry.file_type()?.is_symlink() {
             std::fs::read_link(entry.path())
@@ -108,11 +100,8 @@ impl BlkFile {
         }
     }
 
-    /// Identifies blk file and parses index
-    /// Returns None if this is no blk file
     fn parse_blk_index(file_name: &str, prefix: &str, ext: &str) -> Option<u64> {
         if file_name.starts_with(prefix) && file_name.ends_with(ext) {
-            // Parse blk_index, this means we extract 42 from blk000042.dat
             file_name[prefix.len()..(file_name.len() - ext.len())]
                 .parse::<u64>()
                 .ok()

src/parser/chain.rs

@@ -3,10 +3,9 @@ use crate::parser::index::ChainIndex;
 use crate::parser::types::CoinType;
 use crate::ParserOptions;
 
-/// Manages the index and data of longest valid chain
 pub struct ChainStorage {
     chain_index: ChainIndex,
-    blk_files: std::collections::HashMap<u64, BlkFile>, // maps blk_index to BlkFile
+    blk_files: std::collections::HashMap<u64, BlkFile>,
     coin: CoinType,
     verify: bool,
 }
@@ -21,30 +20,24 @@ impl ChainStorage {
         })
     }
 
-    /// Returns the header of a given height.
     #[must_use]
     pub fn get_header(&mut self, height: u64) -> Option<bitcoin::blockdata::block::Header> {
-        // Read block
         let block_meta = self.chain_index.get(height)?;
         let blk_file = self.blk_files.get_mut(&block_meta.blk_index)?;
         let header = blk_file.read_header(block_meta.data_offset).ok()?;
 
-        // Check if blk file can be closed
         if height == self.chain_index.max_height_by_blk(block_meta.blk_index) {
             blk_file.close();
         }
         Some(header)
     }
 
-    /// Returns the block of a given height.
     #[must_use]
     pub fn get_block(&mut self, height: u64) -> Option<bitcoin::Block> {
-        // Read block
         let block_meta = self.chain_index.get(height)?;
         let blk_file = self.blk_files.get_mut(&block_meta.blk_index)?;
         let block = blk_file.read_block(block_meta.data_offset).ok()?;
 
-        // Check if blk file can be closed
         if height == self.chain_index.max_height_by_blk(block_meta.blk_index) {
             blk_file.close();
         }
@@ -56,8 +49,6 @@ impl ChainStorage {
         Some(block)
     }
 
-    /// Verifies the given block in a chain.
-    /// Panics if not valid
     fn verify(&self, block: &bitcoin::Block, height: u64) -> anyhow::Result<()> {
         assert!(block.check_merkle_root());
         if height == 0 {

src/parser/index.rs

@@ -9,11 +9,10 @@ use crate::ParserOptions;
 const BLOCK_VALID_CHAIN: u64 = 4;
 const BLOCK_HAVE_DATA: u64 = 8;
 
-/// Holds the index of longest valid chain
 pub struct ChainIndex {
     max_height: u64,
     block_index: std::collections::HashMap<u64, BlockIndexRecord>,
-    max_height_blk_index: std::collections::HashMap<u64, u64>, // Maps blk_index to max_height found in the file
+    max_height_blk_index: std::collections::HashMap<u64, u64>,
 }
 
 impl ChainIndex {
@@ -41,7 +40,6 @@ impl ChainIndex {
             Some(_) | None => max_known_height,
         };
 
-        // Filter to only keep relevant block index
         if !options.range.is_default() {
             tracing::info!(target: "index", "Trimming block index from height {} to {} ...", min_height, max_height);
             block_index.retain(|height, _| {
@@ -56,28 +54,23 @@ impl ChainIndex {
         })
     }
 
-    /// Returns the `BlockIndexRecord` for the given height
     pub fn get(&self, height: u64) -> Option<&BlockIndexRecord> {
         self.block_index.get(&height)
     }
 
-    /// Returns the maximum height known
     pub fn max_height(&self) -> u64 {
         self.max_height
     }
 
-    /// Returns the maximum height that can be found in the given blk_index
     pub fn max_height_by_blk(&self, blk_index: u64) -> u64 {
         *self.max_height_blk_index.get(&blk_index).unwrap()
     }
 }
 
-/// Holds the metadata where the block data is stored,
-/// See https://bitcoin.stackexchange.com/questions/28168/what-are-the-keys-used-in-the-blockchain-leveldb-ie-what-are-the-keyvalue-pair
 pub struct BlockIndexRecord {
     pub block_hash: sha256d::Hash,
     pub blk_index: u64,
-    pub data_offset: u64, // offset within the blk file
+    pub data_offset: u64,
     version: u64,
     height: u64,
     status: u64,

src/parser/mod.rs

@@ -9,7 +9,6 @@ mod index;
 pub mod reader;
 pub mod types;
 
-/// Small struct to hold statistics together
 struct WorkerStats {
     pub started_at: Instant,
     pub last_log: Instant,
@@ -27,13 +26,12 @@ impl WorkerStats {
 }
 
 pub struct BlockchainParser {
-    chain_storage: ChainStorage, // Hash storage with the longest chain
-    stats: WorkerStats,          // struct for thread management & statistics
+    chain_storage: ChainStorage,
+    stats: WorkerStats,
     cur_height: u64,
 }
 
 impl BlockchainParser {
-    /// Instantiates a new Parser.
     #[must_use]
     pub fn new(options: &ParserOptions, chain_storage: ChainStorage) -> Self {
         tracing::info!(target: "parser", "Parsing {} blockchain ...", options.coin.name);
@@ -58,7 +56,6 @@ impl BlockchainParser {
         self.on_complete(self.cur_height.saturating_sub(1));
     }
 
-    /// Returns number of remaining blocks
     #[must_use]
     pub fn remaining(&self) -> u64 {
         self.chain_storage

src/parser/reader.rs

@@ -1,18 +1,13 @@
 use bitcoin::consensus::Decodable;
 
-/// Trait for structured reading of blockchain data
 pub trait BlockchainRead: std::io::Read {
-    /// Reads a block as specified here: https://en.bitcoin.it/wiki/Protocol_specification#block
     fn read_block(&mut self) -> anyhow::Result<bitcoin::Block> {
         Ok(bitcoin::Block::consensus_decode(self).unwrap())
     }
 
-    /// Reads a block as specified here: https://en.bitcoin.it/wiki/Protocol_specification#block
     fn read_header(&mut self) -> anyhow::Result<bitcoin::blockdata::block::Header> {
         Ok(bitcoin::blockdata::block::Header::consensus_decode(self).unwrap())
     }
 }
 
-/// All types that implement `Read` get methods defined in `BlockchainRead`
-/// for free.
 impl<R: std::io::Read + ?Sized> BlockchainRead for R {}

src/parser/types.rs

@@ -2,24 +2,18 @@ use bitcoin::hashes::sha256d;
 use std::path::{Path, PathBuf};
 use std::str::FromStr;
 
-/// Trait to specify the underlying coin of a blockchain
-/// Needs a proper magic value and a network id for address prefixes
 pub trait Coin {
-    // Human readable coin name
     fn name(&self) -> String;
-    // Magic value to identify blocks
+
     fn magic(&self) -> u32;
-    // https://en.bitcoin.it/wiki/List_of_address_prefixes
+
     fn version_id(&self) -> u8;
-    // Returns genesis hash
+
     fn genesis(&self) -> sha256d::Hash;
-    // Default working directory to look for datadir, for example .bitcoin
+
     fn default_folder(&self) -> PathBuf;
 }
 
-// Implemented blockchain types.
-// If you want to add you own coin, create a struct with a Coin implementation
-// and add the coin name to from_str() below
 pub struct Bitcoin;
 pub struct TestNet3;
 
@@ -42,7 +36,6 @@ impl Coin for Bitcoin {
     }
 }
 
-/// Bitcoin testnet3
 impl Coin for TestNet3 {
     fn name(&self) -> String {
         String::from("TestNet3")
@@ -63,7 +56,6 @@ impl Coin for TestNet3 {
 }
 
 #[derive(Clone)]
-// Holds the selected coin type information
 pub struct CoinType {
     pub name: String,
     pub magic: u32,

tests/bitcoin.rs

@@ -14,7 +14,6 @@ fn test_bitcoin_genesis() {
 
     assert_eq!(285, genesis.size());
 
-    // Block Header
     assert_eq!(0x0000_0001, genesis.header.version.to_consensus());
     assert_eq!(
         "0000000000000000000000000000000000000000000000000000000000000000",
@@ -29,7 +28,6 @@ fn test_bitcoin_genesis() {
         format!("{}", &genesis.header.block_hash())
     );
 
-    // Check against computed merkle root
     assert_eq!(
         &genesis.header.merkle_root,
         &genesis.compute_merkle_root().unwrap()
@@ -38,11 +36,9 @@ fn test_bitcoin_genesis() {
     assert_eq!(0x1d00_ffff, genesis.header.bits.to_consensus());
     assert_eq!(2_083_236_893, genesis.header.nonce);
 
-    // Tx
     assert_eq!(0x01, genesis.txdata.len());
     assert_eq!(0x0000_0001, genesis.txdata[0].version);
 
-    // Tx Inputs
     assert_eq!(0x01, genesis.txdata[0].input.len());
     assert_eq!(
         "0000000000000000000000000000000000000000000000000000000000000000",
@@ -66,7 +62,6 @@ fn test_bitcoin_genesis() {
         genesis.txdata[0].input[0].sequence.to_consensus_u32()
     );
 
-    // Tx Outputs
     assert_eq!(0x01, genesis.txdata[0].output.len());
     assert_eq!(
         u64::from_be(0x00f2_052a_0100_0000),