Improve help message readability

[janhencic]

Related issue: #260

This PR refactors our Clap command and argument definitions by moving the inline help and long_help attributes into Rust doc comments. The same thing was done with about and long_about attributes. While this causes slightly different output in a few places, it results in more readable and maintainable code overall.

Additionally, the wrap_help feature has been enabled to neatly format these doc comments in the CLI help text, and Cargo.lock now includes the terminal_size crate to support dynamic help wrapping.

[spinus]

@janhencic that's a bit of effort, but why comments rather than explicit command descriptions like before? You mentioned "few places" but, for me it's not clear what impact is, except, we lose explicit cli help definition.

[janhencic]

why comments rather than explicit command descriptions like before?

I switched to doc comments because passing long strings to macro attributes can make the code harder to read. Clap provides an alternative approach. It can parse doc comments, and use them to populate help and long_help messages (same goes for about and long_about).

See Clap docs for more details.

Code Example

Below is an example of the two approaches. The first embeds all help text in the #[arg(...)] macro, while the second moves it into doc comments.

Before

#[derive(Debug, Args)]
pub struct DeployOpts {
    #[arg(
        value_name = "LIMIT",
        default_value_t,
        long,
        help = "Evaluation node limit",
        long_help = r#"Limits the maximum number of hosts to be evaluated at once.
The evaluation process is RAM-intensive. The default behavior is to limit the maximum number of host evaluated at the same time based on naive heuristics.
Set to 0 to disable the limit.
"#
    )]
    eval_node_limit: EvaluationNodeLimit,

After

#[derive(Debug, Args)]
pub struct DeployOpts {
    /// Evaluation node limit
    ///
    /// Limits the maximum number of hosts to be evaluated at once. The evaluation process is
    /// RAM-intensive. The default behavior is to limit the maximum number of hosts evaluated at
    /// the same time based on naive heuristics.
    ///
    /// Set to 0 to disable the limit.
    #[arg(value_name = "LIMIT", default_value_t, long)]

What changes

You mentioned "few places" but, for me it's not clear what impact is, except,
we lose explicit cli help definition.

Help is still explicitly defined—just in a different format. The way it works is that Clap splits doc comments into three distinct sections:

• A short summary
• A blank line
• A detailed description

The short summary becomes the short_help displayed by -h. If there's is a a blank in the doc comment, followed by more text, the entire doc comment becomes the long_help shown with --help.

The catch is that the short summary is now reused within the long help, so you can’t separate them entirely as before. Instead, both pieces of text are concatenated, which means combine them carefully in a way that makes sense. As a result, you may see slight differences in the final result, as compared to before.

Below is an example. I could provide more in a follow up response, if needed.

Command-Line help examples

Short Help (Before & After)

--eval-node-limit <LIMIT>         Evaluation node limit [default: auto]

--eval-node-limit <LIMIT>         Evaluation node limit [default: auto]

Long Help (Before & After)

--eval-node-limit <LIMIT>
    Limits the maximum number of hosts to be evaluated at once.

    The evaluation process is RAM-intensive. The default behavior is to limit the maximum number of host evaluated at the same time based on naive heuristics.

    Set to 0 to disable the limit.


    [default: auto]

--eval-node-limit <LIMIT>
    Evaluation node limit

    Limits the maximum number of hosts to be evaluated at once. The evaluation process is
    RAM-intensive. The default behavior is to limit the maximum number of hosts evaluated at
    the same time based on naive heuristics.

    Set to 0 to disable the limit.

    [default: auto]