Merge pull request #679 from LeoNero/add-simple-comments

Add few comments with some explanations for some decisions

Cargo.toml

@@ -82,7 +82,14 @@ paste = "1.0"
 prost = "0.10.3"
 regex = { version = "1.5", optional = true }
 rustc-hex = "2.1.0"
-serde_crate = { package = "serde", version = "1", features = ["derive"], optional = true }
+# we rename the crate below because there is already a feature called `serde`,
+# so it would conflict with the implicit feature that would be added by adding
+# the `serde` crate;
+# this can be fixed once rust-version is updated to 1.60.0, which solves this
+# by adding the `dep:` prefix for features defined by dependencies
+serde_crate = { package = "serde", version = "1", features = [
+    "derive",
+], optional = true }
 serde_json = { version = "1", optional = true }
 serde_with = { version = "1.8", optional = true }
 serde_yaml = { version = "0.8", optional = true }

src/lib.rs

@@ -42,6 +42,9 @@ extern crate clap;
 extern crate log;
 
 #[cfg(feature = "serde")]
+// on the `[dependencies]` section of `Cargo.toml`, check the comments above
+// the `serde_crate` dependency; we can remove this rename once we move to
+// version 1.60.0 of Rust
 extern crate serde_crate as serde;
 #[cfg(feature = "serde")]
 #[macro_use]

tests/utils/mod.rs

@@ -1,5 +1,11 @@
 //! Various utils to help build functional tests.
 
+// dead code is allowed because there is a possible error in Cargo that warns
+// about dead functions even if they are used;
+// see https://github.com/rust-lang/rust/issues/46379
+// a possible workaround is https://github.com/rust-lang/rust/issues/46379#issuecomment-487421236
+// but as described in https://github.com/rust-lang/rust/issues/46379#issuecomment-487544472,
+// such solution hides code that is truly dead.
 #![allow(dead_code)]
 
 pub mod assert;
@@ -12,7 +18,7 @@ pub fn setup_logging() {
     // set default level to info, debug for node
     // info level is for bitcoin and monero that correspond to `tests/{bitcoin.rs,monero.rs}`
     let env = env_logger::Env::new().default_filter_or("info,farcaster_node=debug");
-    // try init the logger, this fails if logger has been already initialized
+    // try init the logger; this fails if logger has been already initialized
     // and it happens when multiple tests are called as the (test)binary is not restarted
     let _ = env_logger::from_env(env).is_test(true).try_init();
 }