chore(cli): make cli display docs correctly (#14017)

* chore(cli): make cli display docs correctly * ".git/.scripts/commands/fmt/fmt.sh" --------- Co-authored-by: command-bot <>
2026-04-26 21:37:56 +00:00 · 2023-04-27 18:34:15 +08:00
parent ac6e43e628
commit 31e1329da0
17 changed files with 8 additions and 94 deletions
@@ -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)]
@@ -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>,
@@ -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>,
@@ -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,
@@ -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>,
@@ -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,

@@ -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")]
@@ -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,
@@ -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,
@@ -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>,
@@ -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,7 +109,6 @@ 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)]
@@ -121,7 +116,6 @@ pub struct NetworkParams {

 	/// 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)]
@@ -33,16 +33,12 @@ 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.
@@ -50,33 +46,25 @@ pub struct NodeKeyParams {
 	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")]
@@ -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,
 }
@@ -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,
@@ -24,48 +24,26 @@ 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.
-	///
+	///  - 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.
-	///
+	///  - 'archive' Keep all blocks.
+	///  - 'archive-canonical' Keep only finalized blocks.
 	///  - number
-	///
 	///  Keep the last `number` of finalized blocks.
 	#[arg(
 		alias = "keep-blocks",
@@ -25,14 +25,12 @@ use std::path::PathBuf;
 #[derive(Debug, Clone, Args)]
 pub struct SharedParams {
 	/// Specify the chain specification.
-	///
 	/// It can be one of the predefined ones (dev, local, or staging) or it can be a path to a file
 	/// with the chainspec (such as one exported by the `build-spec` subcommand).
 	#[arg(long, value_name = "CHAIN_SPEC")]
 	pub chain: Option<String>,

 	/// Specify the development chain.
-	///
 	/// This flag sets `--chain=dev`, `--force-authoring`, `--rpc-cors=all`,
 	/// `--alice`, and `--tmp` flags, unless explicitly overridden.
 	#[arg(long, conflicts_with_all = &["chain"])]
@@ -43,16 +41,13 @@ pub struct SharedParams {
 	pub base_path: Option<PathBuf>,

 	/// Sets a custom logging filter. Syntax is `<target>=<level>`, e.g. -lsync=debug.
-	///
 	/// Log levels (least to most verbose) are error, warn, info, debug, and trace.
 	/// By default, all targets log `info`. The global log level can be set with `-l<level>`.
 	#[arg(short = 'l', long, value_name = "LOG_PATTERN", num_args = 1..)]
 	pub log: Vec<String>,

 	/// Enable detailed log output.
-	///
 	/// This includes displaying the log target, log level and thread name.
-	///
 	/// This is automatically enabled when something is logged with any higher level than `info`.
 	#[arg(long)]
 	pub detailed_log_output: bool,
@@ -62,10 +57,8 @@ pub struct SharedParams {
 	pub disable_log_color: bool,

 	/// Enable feature to dynamically update and reload the log filter.
-	///
 	/// Be aware that enabling this feature can lead to a performance decrease up to factor six or
 	/// more. Depending on the global logging level the performance decrease changes.
-	///
 	/// The `system_addLogFilter` and `system_resetLogFilter` RPCs will have no effect with this
 	/// option not being set.
 	#[arg(long)]
@@ -22,13 +22,11 @@ use clap::Args;
 #[derive(Debug, Clone, Args)]
 pub struct TelemetryParams {
 	/// Disable connecting to the Substrate telemetry server.
-	///
 	/// Telemetry is on by default on global chains.
 	#[arg(long)]
 	pub no_telemetry: bool,

 	/// The URL of the telemetry server to connect to.
-	///
 	/// This flag can be passed multiple times as a means to specify multiple
 	/// telemetry endpoints. Verbosity levels range from 0-9, with 0 denoting
 	/// the least verbosity.