cli: Improve pruning documentation

[lexnv]

This PR improves the documentation of the pruning modes
exposed as CLI flags.

This specifies what the options mean (ie archive, archive-canonical, or number),
and what the two pruning modes are responsible for (state vs block pruning).

While at it, remove the old note that stated that only finalized blocks
are subject to pruning (which is not entirely true anymore, since we are
also pruning displaced branches -- forks).

Closes #12811.

[cheme]

Sounds good to me.
I'm not entirely sure we should use "finalized (canonical)" in the text or just "finalized" as there can be sometime a reason to distinguished both, but from a user perspective it is not worth doing a distinction.
cc\ @arkpar

[bkchr]

We should change this to:

Suggested change

	/// Options available:
	/// '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.
	///
	/// The default option is to keep the last 256 blocks (number == 256).
	#[arg(alias = "pruning", long, value_name = "PRUNING_MODE")]
	pub state_pruning: Option<String>,
	#[arg(alias = "pruning", long, value_name = "PRUNING_MODE", default = "256")]
	pub state_pruning: PruningMode,

Then add the following enum:

enum PruningMode {
     Archive,
     ArchiveCanonical,
     Custom(u32),
}

impl clap::ValueEnum for PruningMode {
     .. impl the enum
}

[lexnv]

Yep, that does make sense! Thanks for the suggestion!

One problem with ValueEnum is that its happy with unit only enum variants. This is related to the value_variants that requires us to state the expected values. If the Custom(32) is omitted, the default value of "256" cannot be provided anymore.

To overcome this I've changed the ValueEnum to FromStr.
Let me know what you think of it

[bkchr]

Already looks much better, but now we just need to tell clap that these values are enum_values.

[bkchr]

bot merge

[paritytech-processbot]

Waiting for commit status.

[bkchr]

Thank you @lexnv