docs: deny missing docs (#2313)

* docs: deny missing docs * docs: add missing docs for fixed-hash-related crates * docs: add missing docs for logger-related crates * docs: add missing docs for memory-tracker crate * docs: add missing docs for metrics-related crates * ci: fix two ci checks * docs: add missing docs for types crate * docs: fix an incorrect description and two typos according to review comments * docs: add missing docs for ckb-resource * Update resource/src/template.rs Co-authored-by: Boyu Yang <[email protected]> * docs: add todo for missing docs Co-authored-by: Boyu Yang <[email protected]>
nervosnetwork · Oct 30, 2020 · ee0ccec · ee0ccec
1 parent a2aa2cd
commit ee0ccec
Show file tree

Hide file tree

Showing 263 changed files with 3,678 additions and 484 deletions.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -5,7 +5,7 @@ license = "MIT"
 authors = ["Nervos Core Dev <[email protected]>"]
 edition = "2018"
 build = "build.rs"
-description = "TODO(doc): crate description"
+description = "TODO(doc): @doitian crate description"
 homepage = "https://github.com/nervosnetwork/ckb"
 repository = "https://github.com/nervosnetwork/ckb"
 

diff --git a/Makefile b/Makefile
@@ -119,7 +119,7 @@ fmt: setup-ckb-test ## Check Rust source code format to keep to the same style.
 
 .PHONY: clippy
 clippy: setup-ckb-test ## Run linter to examine Rust source codes.
-	cargo clippy ${VERBOSE} --all --all-targets --all-features -- ${CLIPPY_OPTS}
+	cargo clippy ${VERBOSE} --all --all-targets --all-features -- ${CLIPPY_OPTS} -D missing_docs
 	cd test && cargo clippy ${VERBOSE} --all --all-targets --all-features -- ${CLIPPY_OPTS}
 
 .PHONY: security-audit

diff --git a/benches/Cargo.toml b/benches/Cargo.toml
@@ -4,7 +4,7 @@ version = "0.38.0-pre"
 license = "MIT"
 authors = ["Nervos Core Dev <[email protected]>"]
 edition = "2018"
-description = "TODO(doc): crate description"
+description = "TODO(doc): @doitian crate description"
 homepage = "https://github.com/nervosnetwork/ckb"
 repository = "https://github.com/nervosnetwork/ckb"
 

diff --git a/benches/benches/bench_main.rs b/benches/benches/bench_main.rs
@@ -1,3 +1,4 @@
+//! TODO(doc): @doitian
 mod benchmarks;
 
 use criterion::criterion_main;

diff --git a/benches/src/lib.rs b/benches/src/lib.rs
@@ -1 +1,5 @@
-
+//! CKB Benches
+//!
+//! ```console
+//! cd benches && cargo bench --features ci -- --test
+//! ```
diff --git a/build.rs b/build.rs
@@ -1,3 +1,4 @@
+//! Build script for the binary crate `ckb`.
 use std::path::Path;
 
 fn rerun_if_changed(path_str: &str) -> bool {

diff --git a/chain/Cargo.toml b/chain/Cargo.toml
@@ -4,7 +4,7 @@ version = "0.38.0-pre"
 license = "MIT"
 authors = ["Nervos Core Dev <[email protected]>"]
 edition = "2018"
-description = "TODO(doc): crate description"
+description = "TODO(doc): @zhangsoledad crate description"
 homepage = "https://github.com/nervosnetwork/ckb"
 repository = "https://github.com/nervosnetwork/ckb"
 

diff --git a/chain/src/chain.rs b/chain/src/chain.rs
@@ -1,3 +1,4 @@
+//! TODO(doc): @zhangsoledad
 use crate::switch::Switch;
 use ckb_channel::{self as channel, select, Sender};
 use ckb_error::{Error, InternalErrorKind};
@@ -30,6 +31,7 @@ use std::{cmp, thread};
 type ProcessBlockRequest = Request<(Arc<BlockView>, Switch), Result<bool, Error>>;
 type TruncateRequest = Request<Byte32, Result<(), Error>>;
 
+/// TODO(doc): @zhangsoledad
 #[derive(Clone)]
 pub struct ChainController {
     process_block_sender: Sender<ProcessBlockRequest>,
@@ -44,10 +46,12 @@ impl Drop for ChainController {
 }
 
 impl ChainController {
+    /// TODO(doc): @zhangsoledad
     pub fn process_block(&self, block: Arc<BlockView>) -> Result<bool, Error> {
         self.internal_process_block(block, Switch::NONE)
     }
 
+    /// TODO(doc): @zhangsoledad
     pub fn internal_process_block(
         &self,
         block: Arc<BlockView>,
@@ -71,6 +75,7 @@ impl ChainController {
     }
 }
 
+/// TODO(doc): @zhangsoledad
 #[derive(Debug, Default)]
 pub struct ForkChanges {
     // blocks attached to index after forks
@@ -84,26 +89,32 @@ pub struct ForkChanges {
 }
 
 impl ForkChanges {
+    /// TODO(doc): @zhangsoledad
     pub fn attached_blocks(&self) -> &VecDeque<BlockView> {
         &self.attached_blocks
     }
 
+    /// TODO(doc): @zhangsoledad
     pub fn detached_blocks(&self) -> &VecDeque<BlockView> {
         &self.detached_blocks
     }
 
+    /// TODO(doc): @zhangsoledad
     pub fn detached_proposal_id(&self) -> &HashSet<ProposalShortId> {
         &self.detached_proposal_id
     }
 
+    /// TODO(doc): @zhangsoledad
     pub fn has_detached(&self) -> bool {
         !self.detached_blocks.is_empty()
     }
 
+    /// TODO(doc): @zhangsoledad
     pub fn verified_len(&self) -> usize {
         self.attached_blocks.len() - self.dirty_exts.len()
     }
 
+    /// TODO(doc): @zhangsoledad
     #[cfg(debug_assertions)]
     pub fn is_sorted(&self) -> bool {
         IsSorted::is_sorted_by_key(&mut self.attached_blocks().iter(), |blk| {
@@ -135,19 +146,22 @@ impl GlobalIndex {
     }
 }
 
+/// TODO(doc): @zhangsoledad
 pub struct ChainService {
     shared: Shared,
     proposal_table: ProposalTable,
 }
 
 impl ChainService {
+    /// TODO(doc): @zhangsoledad
     pub fn new(shared: Shared, proposal_table: ProposalTable) -> ChainService {
         ChainService {
             shared,
             proposal_table,
         }
     }
 
+    /// TODO(doc): @zhangsoledad
     // remove `allow` tag when https://github.com/crossbeam-rs/crossbeam/issues/404 is solved
     #[allow(clippy::zero_ptr, clippy::drop_copy)]
     pub fn start<S: ToString>(mut self, thread_name: Option<S>) -> ChainController {
@@ -197,6 +211,7 @@ impl ChainService {
         }
     }
 
+    /// TODO(doc): @zhangsoledad
     pub fn external_process_block(&mut self, block: Arc<BlockView>) -> Result<bool, Error> {
         self.process_block(block, Switch::NONE)
     }
@@ -259,6 +274,7 @@ impl ChainService {
         Ok(())
     }
 
+    /// TODO(doc): @zhangsoledad
     // process_block will do block verify
     // but invoker should guarantee block header be verified
     pub fn process_block(&mut self, block: Arc<BlockView>, switch: Switch) -> Result<bool, Error> {

diff --git a/chain/src/switch.rs b/chain/src/switch.rs
@@ -1,17 +1,27 @@
+//! TODO(doc): @zhangsoledad
 #![allow(clippy::unreadable_literal)]
 
 use bitflags::bitflags;
 use ckb_verification::Switch as VerificationSwitch;
 
 bitflags! {
+    /// TODO(doc): @zhangsoledad
     pub struct Switch: u32 {
+        /// TODO(doc): @zhangsoledad
         const NONE                      = 0b00000000;
+        /// TODO(doc): @zhangsoledad
         const DISABLE_EPOCH             = 0b00000001;
+        /// TODO(doc): @zhangsoledad
         const DISABLE_UNCLES            = 0b00000010;
+        /// TODO(doc): @zhangsoledad
         const DISABLE_TWO_PHASE_COMMIT  = 0b00000100;
+        /// TODO(doc): @zhangsoledad
         const DISABLE_DAOHEADER         = 0b00001000;
+        /// TODO(doc): @zhangsoledad
         const DISABLE_REWARD            = 0b00010000;
+        /// TODO(doc): @zhangsoledad
         const DISABLE_NON_CONTEXTUAL    = 0b00100000;
+        /// TODO(doc): @zhangsoledad
         const DISABLE_ALL               = Self::DISABLE_EPOCH.bits | Self::DISABLE_UNCLES.bits |
                                     Self::DISABLE_TWO_PHASE_COMMIT.bits | Self::DISABLE_DAOHEADER.bits |
                                     Self::DISABLE_REWARD.bits |
@@ -20,10 +30,12 @@ bitflags! {
 }
 
 impl Switch {
+    /// TODO(doc): @zhangsoledad
     pub fn disable_all(self) -> bool {
         self.contains(Switch::DISABLE_ALL)
     }
 
+    /// TODO(doc): @zhangsoledad
     pub fn disable_non_contextual(self) -> bool {
         self.contains(Switch::DISABLE_NON_CONTEXTUAL)
     }

diff --git a/ckb-bin/Cargo.toml b/ckb-bin/Cargo.toml
@@ -4,7 +4,7 @@ version = "0.38.0-pre"
 license = "MIT"
 authors = ["Nervos Core Dev <[email protected]>"]
 edition = "2018"
-description = "TODO(doc): crate description"
+description = "TODO(doc): @doitian crate description"
 homepage = "https://github.com/nervosnetwork/ckb"
 repository = "https://github.com/nervosnetwork/ckb"
 

diff --git a/ckb-bin/src/lib.rs b/ckb-bin/src/lib.rs
@@ -1,3 +1,4 @@
+//! TODO(doc): @doitian
 mod helper;
 mod setup_guard;
 mod subcommand;
@@ -10,6 +11,7 @@ use setup_guard::SetupGuard;
 pub(crate) const LOG_TARGET_MAIN: &str = "main";
 pub(crate) const LOG_TARGET_SENTRY: &str = "sentry";
 
+/// TODO(doc): @doitian
 pub fn run_app(version: Version) -> Result<(), ExitCode> {
     // Always print backtrace on panic.
     ::std::env::set_var("RUST_BACKTRACE", "full");

diff --git a/db-migration/Cargo.toml b/db-migration/Cargo.toml
@@ -4,7 +4,7 @@ version = "0.38.0-pre"
 license = "MIT"
 authors = ["Nervos Core Dev <[email protected]>"]
 edition = "2018"
-description = "TODO(doc): crate description"
+description = "TODO(doc): @quake crate description"
 homepage = "https://github.com/nervosnetwork/ckb"
 repository = "https://github.com/nervosnetwork/ckb"
 

diff --git a/db-migration/src/lib.rs b/db-migration/src/lib.rs
@@ -1,3 +1,4 @@
+//! TODO(doc): @quake
 use ckb_db::RocksDB;
 use ckb_error::{Error, InternalErrorKind};
 use ckb_logger::{error, info};
@@ -6,29 +7,34 @@ pub use indicatif::{HumanDuration, MultiProgress, ProgressBar, ProgressDrawTarge
 use std::collections::BTreeMap;
 use std::sync::Arc;
 
+/// TODO(doc): @quake
 pub const VERSION_KEY: &[u8] = b"db-version";
 
 fn internal_error(reason: String) -> Error {
     InternalErrorKind::Database.reason(reason).into()
 }
 
+/// TODO(doc): @quake
 #[derive(Default)]
 pub struct Migrations {
     migrations: BTreeMap<String, Box<dyn Migration>>,
 }
 
 impl Migrations {
+    /// TODO(doc): @quake
     pub fn new() -> Self {
         Migrations {
             migrations: BTreeMap::new(),
         }
     }
 
+    /// TODO(doc): @quake
     pub fn add_migration(&mut self, migration: Box<dyn Migration>) {
         self.migrations
             .insert(migration.version().to_string(), migration);
     }
 
+    /// TODO(doc): @quake
     pub fn migrate(&self, mut db: RocksDB) -> Result<RocksDB, Error> {
         let db_version = db
             .get_pinned_default(VERSION_KEY)
@@ -91,7 +97,9 @@ impl Migrations {
     }
 }
 
+/// TODO(doc): @quake
 pub trait Migration {
+    /// TODO(doc): @quake
     fn migrate(
         &self,
         _db: RocksDB,
@@ -102,11 +110,13 @@ pub trait Migration {
     fn version(&self) -> &str;
 }
 
+/// TODO(doc): @quake
 pub struct DefaultMigration {
     version: String,
 }
 
 impl DefaultMigration {
+    /// TODO(doc): @quake
     pub fn new(version: &str) -> Self {
         Self {
             version: version.to_string(),

diff --git a/db/Cargo.toml b/db/Cargo.toml
@@ -4,7 +4,7 @@ version = "0.38.0-pre"
 license = "MIT"
 authors = ["Nervos Core Dev <[email protected]>"]
 edition = "2018"
-description = "TODO(doc): crate description"
+description = "TODO(doc): @quake crate description"
 homepage = "https://github.com/nervosnetwork/ckb"
 repository = "https://github.com/nervosnetwork/ckb"