More docs

bin/subalfred/src/command/get/runtime_upgrade_block.rs

@@ -4,7 +4,7 @@ use clap::Args;
 use crate::prelude::*;
 use subalfred_core::node;
 
-/// Try to get the runtime upgrade block.
+/// Get the runtime upgrade block.
 ///
 /// Using the dichotomy algorithm to find it out.
 /// This operation will fail if the runtime version does not existed.

bin/subalfred/src/command/state/mod.rs

@@ -10,7 +10,7 @@ use fork_off::ForkOffCmd;
 mod r#override;
 use r#override::OverrideCmd;
 
-/// A set of tools to process Substrate-like node state.
+/// A set of tools to process Substrate-like chain state.
 #[cmd_impl::cmd]
 pub(crate) enum StateCmd {
 	Diff,

bin/subalfred/src/main.rs

@@ -3,7 +3,7 @@
 //! Subalfred CLI start entry point.
 
 mod prelude {
-	pub use ::std::result::Result as StdResult;
+	pub use std::result::Result as StdResult;
 
 	pub use anyhow::Result;
 

lib/core/src/cargo/mod.rs

@@ -1,4 +1,4 @@
-//! Core library about how Subalfred interacts with Cargo.
+//! Subalfred core Cargo library.
 
 #[cfg(test)] mod test;
 
@@ -13,7 +13,7 @@ use regex::Captures;
 // hack-ink
 use crate::{prelude::*, system};
 
-/// Get the item from the given source by id.
+/// Provide a method to get the item by id from specific source.
 pub trait GetById<'a> {
 	/// Id type.
 	type Id;
@@ -72,19 +72,10 @@ pub fn members(metadata: &Metadata) -> Option<Vec<&Package>> {
 	metadata.workspace_members.iter().map(|id| util::find_package(metadata, id)).collect()
 }
 
-// TODO: might be useless
-// /// Read the [`Manifest`] from the given path.
-// pub fn manifest<P>(path: P) -> Result<Manifest>
-// where
-// 	P: AsRef<Path>,
-// {
-// 	Ok(Manifest::from_path(path).map_err(error::Cargo::OpenManifestFailed)?)
-// }
-
 // TODO: optimize the algorithm
 /// Update all the workspace members' versions with the given one.
 ///
-/// If a workspace member depends on another one, the dependency will also be updated.
+/// If a workspace member depends on other members, this will also update the dependencies.
 pub async fn update_member_versions(manifest_path: &str, to: &str) -> Result<()> {
 	let metadata = metadata(manifest_path)?;
 	let members = if let Some(members) = members(&metadata) {

lib/core/src/error/mod.rs

@@ -27,7 +27,7 @@ pub enum Error {
 	Tokio(#[from] Tokio),
 }
 
-/// Print the error directly.
+/// An error helper/wrapper to debug/print the error quickly.
 #[derive(Debug)]
 pub struct Quick(String);
 impl std::fmt::Display for Quick {
@@ -36,9 +36,7 @@ impl std::fmt::Display for Quick {
 	}
 }
 impl std::error::Error for Quick {}
-/// Quick debug helper.
-///
-/// Convert the error to [`Quick`].
+/// Wrap the error with [`Quick`].
 pub fn quick_err<E>(e: E) -> Quick
 where
 	E: std::fmt::Debug,
@@ -60,9 +58,6 @@ pub enum Cargo {
 	GetPackageFailed,
 	#[error("[core::cargo] failed to get the root package")]
 	GetRootPackageFailed,
-	// TODO: might be useless
-	// #[error("[core::cargo] failed to open the manifest file")]
-	// OpenManifestFailed(#[source] cargo_toml::Error),
 }
 
 /// Generic error.
@@ -84,7 +79,7 @@ pub enum Generic {
 	#[error(transparent)]
 	Tungstenite(#[from] tokio_tungstenite::tungstenite::Error),
 }
-/// [`Generic::AlmostImpossible`] error helper.
+/// Wrap the error with [`Generic::AlmostImpossible`].
 pub fn almost_impossible(e_msg: &'static str) -> Generic {
 	Generic::AlmostImpossible(e_msg)
 }

lib/core/src/http/mod.rs

@@ -1,4 +1,4 @@
-//! Core library about how Subalfred interacts with HTTP.
+//! Subalfred core HTTP library.
 
 // std
 use std::sync::Arc;

lib/core/src/jsonrpc/http/mod.rs

@@ -1,4 +1,4 @@
-//! Minimal JSONRPC HTTP client implementation.
+//! Minimal HTTP JSONRPC client implementation.
 
 #[cfg(test)] mod test;
 

lib/core/src/jsonrpc/mod.rs

@@ -1,4 +1,4 @@
-//! Core library about how Subalfred interacts with JSONRPC.
+//! Subalfred core JSONRPC library.
 
 pub mod http;
 pub mod ws;

lib/core/src/jsonrpc/ws/mod.rs

@@ -1,4 +1,4 @@
-//! Full functionality JSONRPC websocket client implementation.
+//! Full functionality WS JSONRPC client implementation.
 //! Follow <https://www.jsonrpc.org/specification> specification.
 
 // std
@@ -33,7 +33,7 @@ type BatchResponse = Vec<RequestResponse>;
 type BatchNotifier = oneshot::Sender<BatchResponse>;
 type BatchPool = FxHashMap<Id, BatchNotifier>;
 
-/// The websocket initializer.
+/// The WS initializer.
 #[derive(Debug)]
 pub struct Initializer {
 	/// Concurrent tasks count limit.
@@ -70,7 +70,7 @@ impl Initializer {
 		self
 	}
 
-	/// Initialize the websocket stream.
+	/// Initialize the WS stream.
 	pub async fn connect(self, uri: &str) -> Result<Ws> {
 		let (mut ws_tx, mut ws_rx) = tokio_tungstenite::connect_async(uri)
 			.await

lib/core/src/key/mod.rs

@@ -1,4 +1,4 @@
-//! Substrate keys implementations.
+//! Subalfred core key library.
 
 // std
 use std::{
@@ -10,7 +10,7 @@ use parity_scale_codec::{Decode, Encode};
 // hack-ink
 use crate::prelude::*;
 
-/// Substrate/Polkadot keys like.
+/// Substrate-like key trait.
 pub trait Key
 where
 	Self: Sized,
@@ -24,7 +24,7 @@ where
 	/// Sub-seed, used to derive the key.
 	fn sub_seed(self) -> Self::SubSeed;
 
-	/// Convert the [`KeyTypeId`] to `[u8; N]`
+	/// Convert the [`KeyTypeId`] into `[u8; N]`.
 	fn to_key<const N: usize>(self) -> Result<[u8; N]> {
 		let mut result = [0; N];
 		let sub_seed = self.sub_seed();
@@ -92,13 +92,13 @@ macro_rules! impl_keys {
 	};
 }
 impl_keys! {
-	#[doc="Unique identifier of a pallet, aka `ModuleId`."]
+	#[doc="Identifier of a pallet, aka `ModuleId`."]
 	#[id=*b"modl"]
 	PalletId([u8; 8]),
-	#[doc="Unique identifier of a parachain."]
+	#[doc="Identifier of a parachain."]
 	#[id=*b"para"]
 	ParaId(u32),
-	#[doc="Unique identifier of a sibling chain."]
+	#[doc="Identifier of a sibling chain."]
 	#[id=*b"sibl"]
 	SiblId(u32),
 }

lib/core/src/lib.rs

@@ -13,12 +13,12 @@ pub mod substrate_client;
 pub mod system;
 
 pub mod prelude {
-	//! Subalfred core libraries prelude.
+	//! Subalfred core prelude.
 
-	pub use ::std::result::Result as StdResult;
+	pub use std::result::Result as StdResult;
 
 	pub use super::error::{self, Error};
 
-	/// Subalfred core lib's `Result` type.
-	pub type Result<T> = ::std::result::Result<T, Error>;
+	/// Subalfred core libraries' `Result` type.
+	pub type Result<T> = StdResult<T, Error>;
 }

lib/core/src/node/mod.rs

@@ -1,4 +1,4 @@
-//! Core library about how Subalfred interacts with Substrate-based node.
+//! Subalfred core node library.
 
 // std
 use std::{
@@ -21,7 +21,7 @@ const E_CODEC_METADATA_IS_NON_HEX: &str =
 const E_STDERR_IS_EMPTY: &str =
 	"[core::node] `stderr` is empty, , maybe the substrate node behavior changed";
 
-/// Spawn a Substrate-Base standard node.
+/// Spawn a Substrate-like standard node.
 pub fn spawn(executable: &str, rpc_port: u16, chain: &str) -> Result<Child> {
 	let mut node = Command::new(executable)
 		.stdout(Stdio::null())
@@ -47,14 +47,14 @@ pub fn spawn(executable: &str, rpc_port: u16, chain: &str) -> Result<Child> {
 	Ok(node)
 }
 
-/// Get runtime version from node.
+/// Get runtime version from a nodes's HTTP RPC endpoint.
 pub async fn runtime_version(uri: &str) -> Result<RuntimeVersion> {
 	Ok(http::send::<_, RuntimeVersion>(uri, &state::get_runtime_version(0, None::<()>))
 		.await?
 		.result)
 }
 
-/// Fetch runtime metadata from node.
+/// Fetch runtime metadata from a nodes's HTTP RPC endpoint.
 pub async fn runtime_metadata(uri: &str) -> Result<LatestRuntimeMetadata> {
 	let response = http::send::<_, String>(uri, &state::get_metadata(0, None::<()>)).await?;
 
@@ -81,7 +81,7 @@ pub async fn find_runtime_upgrade_block(
 	// subalfred
 	use crate::{
 		jsonrpc::ws::Initializer,
-		substrate_client::{BasicApi, Client},
+		substrate_client::{Apis, Client},
 	};
 
 	let client = Client::initialize(Initializer::new(), uri).await?;

lib/core/src/ss58/mod.rs

@@ -1,4 +1,4 @@
-//! SS58-prefix address algorithm implementation.
+//! Subalfred core SS58 library.
 
 #[cfg(test)] mod test;
 
@@ -18,9 +18,9 @@ pub struct Address<'a> {
 	pub value: String,
 }
 
-/// Generate the public key and the specific network address of address.
+/// calculate the public key of the address and the network's corresponding address.
 ///
-/// `address` could be public key or SS58 address.
+/// `address` could be a public key or SS58 address.
 /// `network` is case insensitive.
 pub fn of<'a>(address: &str, network: &'a str) -> Result<(Vec<u8>, String, Address<'a>)> {
 	let public_key = recover_public_key(address)?;
@@ -31,9 +31,9 @@ pub fn of<'a>(address: &str, network: &'a str) -> Result<(Vec<u8>, String, Addre
 	Ok((public_key, hex_public_key, Address { network, prefix, value: address }))
 }
 
-/// Generate the public key and all the network addresses of the address.
+/// calculate the public key and all the specific network addresses of the network.
 ///
-/// `address` could be public key or SS58 address.
+/// `address` could be a public key or SS58 address.
 pub fn all(address: &str) -> Result<(Vec<u8>, String, Vec<Address>)> {
 	let public_key = recover_public_key(address)?;
 	let hex_public_key = array_bytes::bytes2hex("0x", &public_key);
@@ -51,7 +51,7 @@ pub fn all(address: &str) -> Result<(Vec<u8>, String, Vec<Address>)> {
 
 // Recover the public key from the given address.
 //
-// `address` could be public key or SS58 address.
+// `address` could be a public key or SS58 address.
 // NO-OP, If the `address` is already a public key.
 fn recover_public_key(address: &str) -> Result<Vec<u8>> {
 	match address.len() {

lib/core/src/state/diff.rs

@@ -5,11 +5,10 @@ use std::path::Path;
 // hack-ink
 use crate::prelude::*;
 
-/// Check the diff between two states.
-///
+/// Check the differences between the two states.
 /// Note:
-/// This is not a symmetric diff.
-/// `a.diff(b)` may equals to `b.diff(a)`, but not always.
+/// This is not a symmetric difference operation.
+/// `a.diff(b)` might equal `b.diff(a)`, but not always.
 pub fn diff<P>(a: P, b: P) -> Result<Vec<String>>
 where
 	P: Send + AsRef<Path>,
@@ -31,7 +30,7 @@ where
 				diff.push(format!("-{a_k}:{a_v}\n+{a_k}:{b_v}"));
 			}
 
-		// Completely same.
+		// Completely the same.
 		}
 		// Keys only appear in a.
 		else {

lib/core/src/state/export.rs

@@ -13,12 +13,16 @@ use crate::{
 	jsonrpc::ws::Initializer,
 	node,
 	prelude::*,
-	substrate_client::{BasicApi, Client},
+	substrate_client::{Apis, Client},
 	system,
 };
 use substorager::StorageKey;
 
-/// Export the chain state..
+/// Export the chain state from a node's WS RPC endpoint at a specific block height.
+///
+/// If `at` is `None`, this will start from the latest block.
+/// Use `skip_pallets` to skip the exporting of some pallets, we usually use this when the pallet's
+/// data is too large.
 pub async fn export(
 	uri: &str,
 	at: Option<String>,

lib/core/src/state/fork_off.rs

@@ -66,7 +66,7 @@ pub struct ForkOffConfig {
 	pub disable_default_bootnodes: bool,
 }
 
-/// Fork-off the state.
+/// Fork-off the state with the specific configurations.
 pub fn fork_off<P>(target_chain_spec_path: P, config: &ForkOffConfig) -> Result<()>
 where
 	P: AsRef<Path>,

lib/core/src/state/mod.rs

@@ -1,4 +1,4 @@
-//! State core library.
+//! Subalfred core runtime state library.
 
 pub mod diff;
 pub use diff::*;

lib/core/src/state/override.rs

@@ -5,7 +5,7 @@ use std::path::Path;
 // hack-ink
 use crate::prelude::*;
 
-/// Override state a with b.
+/// Override the state a with b.
 pub fn r#override<P>(a: P, b: P) -> Result<()>
 where
 	P: Send + AsRef<Path>,

lib/core/src/substrate_client/api.rs

@@ -3,9 +3,9 @@
 // subalfred
 use crate::prelude::*;
 
-///  Substrate-like basic API collections.
+/// Substrate-like basic API collections.
 #[async_trait::async_trait]
-pub trait BasicApi {
+pub trait Apis {
 	/// TODO: doc
 	async fn get_block_hash<BlockNumber>(
 		&self,
@@ -43,7 +43,4 @@ pub trait BasicApi {
 		prefix: substorager::StorageKey,
 		at: Option<String>,
 	) -> Result<Vec<(String, String)>>;
-
-	// async fn get_keys_paged(&self, prefix: substorager::StorageKey, at: Option<String>) ->
-	// Result<Vec<String>>;
 }