Improving Readability of long_help Messages

[janhencic]

Hello everyone 👋,

Improving Readability of long_help Messages

I was reading the Colmena source code and noticed that in many places where the Args procedural macro is used, the long_help attribute often contains lengthy strings. These strings typically need to be split across multiple lines, which can make the code less readable.

For example:

#[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 hosts evaluated at the same time based on naive heuristics.

Set to 0 to disable the limit.
"#
    )]

Because these strings span multiple lines, it can be difficult to read and maintain. One solution would be to move both the help and long_help attributes into doc comments above each struct field:

#[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)]
    eval_node_limit: EvaluationNodeLimit,
}

Here, the first line of the doc comment becomes the help message, while subsequent lines become the long_help message. Each newline in the doc comment is preserved in the final help output.

Word Wrapping

Additionally, we could enable the word_wrap feature in Clap and set it to a reasonable limit (e.g. 80 or 100). This would produce more readable help messages in commands such as:

colmena --help
colmena apply --help

Conclusion

If the maintainers believe these changes would be helpful, I’d be happy to implement them. The plan is to:

• Move all help and long_help fields into doc comments for improved readability.
• Enable the word_wrap feature for cleaner and more consistent help messages.

Please let me know what you think!

[zhaofengli]

Hi, I think this suggestion makes sense. Let's do it 👍

[janhencic]

Thank you, @zhaofengli! I’ll go ahead and create a pull request.