chore(cli): make cli display docs correctly

client/cli/src/commands/build_spec_cmd.rs

@@ -38,7 +38,6 @@ pub struct BuildSpecCmd {
 	pub raw: bool,
 
 	/// Disable adding the default bootnode to the specification.
-	///
 	/// By default the `/ip4/127.0.0.1/tcp/30333/p2p/NODE_PEER_ID` bootnode is added to the
 	/// specification when no bootnode exists.
 	#[arg(long)]

client/cli/src/commands/check_block_cmd.rs

@@ -29,12 +29,11 @@ use std::{fmt::Debug, str::FromStr, sync::Arc};
 /// The `check-block` command used to validate blocks.
 #[derive(Debug, Clone, Parser)]
 pub struct CheckBlockCmd {
-	/// Block hash or number
+	/// Block hash or number.
 	#[arg(value_name = "HASH or NUMBER")]
 	pub input: BlockNumberOrHash,
 
 	/// The default number of 64KB pages to ever allocate for Wasm execution.
-	///
 	/// Don't alter this unless you know what you're doing.
 	#[arg(long, value_name = "COUNT")]
 	pub default_heap_pages: Option<u32>,

client/cli/src/commands/export_blocks_cmd.rs

@@ -36,13 +36,11 @@ pub struct ExportBlocksCmd {
 	pub output: Option<PathBuf>,
 
 	/// Specify starting block number.
-	///
 	/// Default is 1.
 	#[arg(long, value_name = "BLOCK")]
 	pub from: Option<GenericNumber>,
 
 	/// Specify last block number.
-	///
 	/// Default is best block.
 	#[arg(long, value_name = "BLOCK")]
 	pub to: Option<GenericNumber>,

client/cli/src/commands/generate_node_key.rs

@@ -35,13 +35,11 @@ use std::{
 )]
 pub struct GenerateNodeKeyCmd {
 	/// Name of file to save secret key to.
-	///
 	/// If not given, the secret key is printed to stdout.
 	#[arg(long)]
 	file: Option<PathBuf>,
 
 	/// The output is in raw binary format.
-	///
 	/// If not given, the output is written as an hex encoded string.
 	#[arg(long)]
 	bin: bool,

client/cli/src/commands/import_blocks_cmd.rs

@@ -41,7 +41,6 @@ pub struct ImportBlocksCmd {
 	pub input: Option<PathBuf>,
 
 	/// The default number of 64KB pages to ever allocate for Wasm execution.
-	///
 	/// Don't alter this unless you know what you're doing.
 	#[arg(long, value_name = "COUNT")]
 	pub default_heap_pages: Option<u32>,

client/cli/src/commands/insert_key.rs

@@ -36,7 +36,7 @@ pub struct InsertKeyCmd {
 	#[arg(long)]
 	suri: Option<String>,
 
-	/// Key type, examples: "gran", or "imon"
+	/// Key type, examples: "gran", or "imon".
 	#[arg(long)]
 	key_type: String,
 

client/cli/src/commands/inspect_key.rs

@@ -34,12 +34,9 @@ use std::str::FromStr;
 pub struct InspectKeyCmd {
 	/// A Key URI to be inspected. May be a secret seed, secret URI
 	/// (with derivation paths and password), SS58, public URI or a hex encoded public key.
-	///
 	/// If it is a hex encoded public key, `--public` needs to be given as argument.
-	///
 	/// If the given value is a file, the file content will be used
 	/// as URI.
-	///
 	/// If omitted, you will be prompted for the URI.
 	uri: Option<String>,
 
@@ -64,12 +61,10 @@ pub struct InspectKeyCmd {
 	pub crypto_scheme: CryptoSchemeFlag,
 
 	/// Expect that `--uri` has the given public key/account-id.
-	///
 	/// If `--uri` has any derivations, the public key is checked against the base `uri`, i.e. the
 	/// `uri` without any derivation applied. However, if `uri` has a password or there is one
 	/// given by `--password`, it will be used to decrypt `uri` before comparing the public
 	/// key/account-id.
-	///
 	/// If there is no derivation in `--uri`, the public key will be checked against the public key
 	/// of `--uri` directly.
 	#[arg(long, conflicts_with = "public")]

client/cli/src/commands/inspect_node_key.rs

@@ -34,13 +34,11 @@ use std::{
 )]
 pub struct InspectNodeKeyCmd {
 	/// Name of file to read the secret key from.
-	///
 	/// If not given, the secret key is read from stdin (up to EOF).
 	#[arg(long)]
 	file: Option<PathBuf>,
 
 	/// The input is in raw binary format.
-	///
 	/// If not given, the input is read as an hex encoded string.
 	#[arg(long)]
 	bin: bool,

client/cli/src/commands/run_cmd.rs

@@ -38,7 +38,6 @@ use std::net::{IpAddr, Ipv4Addr, SocketAddr};
 #[derive(Debug, Clone, Parser)]
 pub struct RunCmd {
 	/// Enable validator mode.
-	///
 	/// The node will be started with the authority role and actively
 	/// participate in any consensus task that it can (e.g. depending on
 	/// availability of local keys).
@@ -51,7 +50,6 @@ pub struct RunCmd {
 	pub no_grandpa: bool,
 
 	/// Listen to all RPC interfaces.
-	///
 	/// Default is local. Note: not all RPC methods are safe to be exposed publicly. Use an RPC
 	/// proxy server to filter out dangerous methods. More details:
 	/// <https://docs.substrate.io/main-docs/build/custom-rpc/#public-rpcs>.
@@ -60,13 +58,11 @@ pub struct RunCmd {
 	pub rpc_external: bool,
 
 	/// Listen to all RPC interfaces.
-	///
 	/// Same as `--rpc-external`.
 	#[arg(long)]
 	pub unsafe_rpc_external: bool,
 
 	/// RPC methods to expose.
-	///
 	/// - `unsafe`: Exposes every RPC method.
 	/// - `safe`: Exposes only a safe subset of RPC methods, denying unsafe RPC methods.
 	/// - `auto`: Acts as `safe` if RPC is served externally, e.g. when `--{rpc,ws}-external` is
@@ -82,7 +78,6 @@ pub struct RunCmd {
 	pub rpc_methods: RpcMethods,
 
 	/// Listen to all Websocket interfaces.
-	///
 	/// Default is local. Note: not all RPC methods are safe to be exposed publicly. Use an RPC
 	/// proxy server to filter out dangerous methods. More details:
 	/// <https://docs.substrate.io/main-docs/build/custom-rpc/#public-rpcs>.
@@ -91,7 +86,6 @@ pub struct RunCmd {
 	pub ws_external: bool,
 
 	/// Listen to all Websocket interfaces.
-	///
 	/// Same as `--ws-external` but doesn't warn you about it.
 	#[arg(long)]
 	pub unsafe_ws_external: bool,
@@ -137,7 +131,6 @@ pub struct RunCmd {
 	pub ws_max_out_buffer_capacity: Option<usize>,
 
 	/// Specify browser Origins allowed to access the HTTP & WS RPC servers.
-	///
 	/// A comma-separated list of origins (protocol://domain or special `null`
 	/// value). Value of `all` will disable origin validation. Default is to
 	/// allow localhost and <https://polkadot.js.org> origins. When running in
@@ -146,7 +139,6 @@ pub struct RunCmd {
 	pub rpc_cors: Option<Cors>,
 
 	/// The human-readable name for this node.
-	///
 	/// It's used as network node name.
 	#[arg(long, value_name = "NAME")]
 	pub name: Option<String>,
@@ -225,13 +217,10 @@ pub struct RunCmd {
 	pub force_authoring: bool,
 
 	/// Run a temporary node.
-	///
 	/// A temporary directory will be created to store the configuration and will be deleted
 	/// at the end of the process.
-	///
 	/// Note: the directory is random per process execution. This directory is used as base path
 	/// which includes: database, node key and keystore.
-	///
 	/// When `--dev` is given and no explicit `--base-path`, this option is implied.
 	#[arg(long, conflicts_with = "base_path")]
 	pub tmp: bool,

client/cli/src/params/import_params.rs

@@ -52,15 +52,11 @@ pub struct ImportParams {
 	pub wasm_method: WasmExecutionMethod,
 
 	/// The WASM instantiation method to use.
-	///
 	/// Only has an effect when `wasm-execution` is set to `compiled`.
-	///
 	/// The copy-on-write strategies are only supported on Linux.
 	/// If the copy-on-write variant of a strategy is unsupported
 	/// the executor will fall back to the non-CoW equivalent.
-	///
 	/// The fastest (and the default) strategy available is `pooling-copy-on-write`.
-	///
 	/// The `legacy-instance-reuse` strategy is deprecated and will
 	/// be removed in the future. It should only be used in case of
 	/// issues with the default instantiation strategy.
@@ -73,7 +69,6 @@ pub struct ImportParams {
 	pub wasmtime_instantiation_strategy: WasmtimeInstantiationStrategy,
 
 	/// Specify the path where local WASM runtimes are stored.
-	///
 	/// These runtimes will override on-chain runtimes when the version matches.
 	#[arg(long, value_name = "PATH")]
 	pub wasm_runtime_overrides: Option<PathBuf>,
@@ -83,13 +78,11 @@ pub struct ImportParams {
 	pub execution_strategies: ExecutionStrategiesParams,
 
 	/// Specify the state cache size.
-	///
 	/// Providing `0` will disable the cache.
 	#[arg(long, value_name = "Bytes", default_value_t = 67108864)]
 	pub trie_cache_size: usize,
 
 	/// DEPRECATED
-	///
 	/// Switch to `--trie-cache-size`.
 	#[arg(long)]
 	state_cache_size: Option<usize>,

client/cli/src/params/network_params.rs

@@ -42,9 +42,7 @@ pub struct NetworkParams {
 	pub reserved_nodes: Vec<MultiaddrWithPeerId>,
 
 	/// Whether to only synchronize the chain with reserved nodes.
-	///
 	/// Also disables automatic peer discovery.
-	///
 	/// TCP connections might still be established with non-reserved nodes.
 	/// In particular, if you are a validator your node might still connect to other
 	/// validator nodes and collator nodes regardless of whether they are defined as
@@ -95,14 +93,12 @@ pub struct NetworkParams {
 	pub in_peers_light: u32,
 
 	/// Disable mDNS discovery.
-	///
 	/// By default, the network will use mDNS to discover other nodes on the
 	/// local network. This disables it. Automatically implied when using --dev.
 	#[arg(long)]
 	pub no_mdns: bool,
 
 	/// Maximum number of peers from which to ask for the same blocks in parallel.
-	///
 	/// This allows downloading announced blocks from multiple peers. Decrease to save
 	/// traffic and risk increased latency.
 	#[arg(long, value_name = "COUNT", default_value_t = 5)]
@@ -113,15 +109,13 @@ pub struct NetworkParams {
 	pub node_key_params: NodeKeyParams,
 
 	/// Enable peer discovery on local networks.
-	///
 	/// By default this option is `true` for `--dev` or when the chain type is
 	/// `Local`/`Development` and false otherwise.
 	#[arg(long)]
 	pub discover_local: bool,
 
 	/// Require iterative Kademlia DHT queries to use disjoint paths for increased resiliency in
 	/// the presence of potentially adversarial nodes.
-	///
 	/// See the S/Kademlia paper for more information on the high level design as well as its
 	/// security improvements.
 	#[arg(long)]

client/cli/src/params/node_key_params.rs

@@ -33,50 +33,38 @@ const NODE_KEY_ED25519_FILE: &str = "secret_ed25519";
 #[derive(Debug, Clone, Args)]
 pub struct NodeKeyParams {
 	/// The secret key to use for libp2p networking.
-	///
 	/// The value is a string that is parsed according to the choice of
 	/// `--node-key-type` as follows:
-	///
 	///   `ed25519`:
 	///   The value is parsed as a hex-encoded Ed25519 32 byte secret key,
 	///   i.e. 64 hex characters.
-	///
 	/// The value of this option takes precedence over `--node-key-file`.
-	///
 	/// WARNING: Secrets provided as command-line arguments are easily exposed.
 	/// Use of this option should be limited to development and testing. To use
 	/// an externally managed secret key, use `--node-key-file` instead.
 	#[arg(long, value_name = "KEY")]
 	pub node_key: Option<String>,
 
 	/// The type of secret key to use for libp2p networking.
-	///
 	/// The secret key of the node is obtained as follows:
-	///
 	///   * If the `--node-key` option is given, the value is parsed as a secret key according to
 	///     the type. See the documentation for `--node-key`.
-	///
 	///   * If the `--node-key-file` option is given, the secret key is read from the specified
 	///     file. See the documentation for `--node-key-file`.
-	///
 	///   * Otherwise, the secret key is read from a file with a predetermined, type-specific name
 	///     from the chain-specific network config directory inside the base directory specified by
 	///     `--base-dir`. If this file does not exist, it is created with a newly generated secret
 	///     key of the chosen type.
-	///
 	/// The node's secret key determines the corresponding public key and hence the
 	/// node's peer ID in the context of libp2p.
 	#[arg(long, value_name = "TYPE", value_enum, ignore_case = true, default_value_t = NodeKeyType::Ed25519)]
 	pub node_key_type: NodeKeyType,
 
 	/// The file from which to read the node's secret key to use for libp2p networking.
-	///
 	/// The contents of the file are parsed according to the choice of `--node-key-type`
 	/// as follows:
-	///
 	///   `ed25519`:
 	///   The file must contain an unencoded 32 byte or hex encoded Ed25519 secret key.
-	///
 	/// If the file does not exist, it is created with a newly generated secret key of
 	/// the chosen type.
 	#[arg(long, value_name = "FILE")]

client/cli/src/params/offchain_worker_params.rs

@@ -33,7 +33,6 @@ use crate::{error, OffchainWorkerEnabled};
 #[derive(Debug, Clone, Args)]
 pub struct OffchainWorkerParams {
 	/// Should execute offchain workers on every block.
-	///
 	/// By default it's only enabled for nodes that are authoring new blocks.
 	#[arg(
 		long = "offchain-worker",
@@ -45,9 +44,7 @@ pub struct OffchainWorkerParams {
 	pub enabled: OffchainWorkerEnabled,
 
 	/// Enable Offchain Indexing API, which allows block import to write to Offchain DB.
-	///
-	/// Enables a runtime to write directly to a offchain workers
-	/// DB during block import.
+	/// Enables a runtime to write directly to a offchain workers DB during block import.
 	#[arg(long = "enable-offchain-indexing", value_name = "ENABLE_OFFCHAIN_INDEXING", default_value_t = false, action = ArgAction::Set)]
 	pub indexing_enabled: bool,
 }

client/cli/src/params/prometheus_params.rs

@@ -27,12 +27,10 @@ pub struct PrometheusParams {
 	#[arg(long, value_name = "PORT")]
 	pub prometheus_port: Option<u16>,
 	/// Expose Prometheus exporter on all interfaces.
-	///
 	/// Default is local.
 	#[arg(long)]
 	pub prometheus_external: bool,
 	/// Do not expose a Prometheus exporter endpoint.
-	///
 	/// Prometheus metric endpoint is enabled by default.
 	#[arg(long)]
 	pub no_prometheus: bool,

client/cli/src/params/pruning_params.rs

@@ -24,48 +24,31 @@ use sc_service::{BlocksPruning, PruningMode};
 #[derive(Debug, Clone, Args)]
 pub struct PruningParams {
 	/// Specify the state pruning mode.
-	///
 	/// This mode specifies when the block's state (ie, storage)
 	/// should be pruned (ie, removed) from the database.
-	///
 	/// This setting can only be set on the first creation of the database. Every subsequent run
 	/// will load the pruning mode from the database and will error if the stored mode doesn't
 	/// match this CLI value. It is fine to drop this CLI flag for subsequent runs.
-	///
 	/// Possible values:
-	///
 	///  - archive:
-	///
 	///    Keep the state of all blocks.
-	///
 	///  - 'archive-canonical'
-	///
 	///    Keep only the state of finalized blocks.
-	///
 	///  - number
-	///
 	///    Keep the state of the last number of finalized blocks.
-	///
 	/// [default: 256]
 	#[arg(alias = "pruning", long, value_name = "PRUNING_MODE")]
 	pub state_pruning: Option<DatabasePruningMode>,
 
 	/// Specify the blocks pruning mode.
-	///
 	/// This mode specifies when the block's body (including justifications)
 	/// should be pruned (ie, removed) from the database.
-	///
 	/// Possible values:
 	///  - 'archive'
-	///
 	///    Keep all blocks.
-	///
 	///  - 'archive-canonical'
-	///
 	///    Keep only finalized blocks.
-	///
 	///  - number
-	///
 	///  Keep the last `number` of finalized blocks.
 	#[arg(
 		alias = "keep-blocks",