clap always prints short help (even with `--help`) if all help messages set with #[arg(help = "...")]

[Sk7Str1p3]

Please complete the following tasks

• I have searched the discussions
• I have searched the open and rejected issues

Rust Version

rustc 1.93.0-nightly (25d319a0f 2025-11-11)

Clap Version

4.5.53

Minimal reproducible code

#[derive(clap::Parser)]
struct Cli {
    #[arg(
        short,
        default_value = "hello",
        help = "\
        do some job

\
        the job is print hello world\
        "
    )]
    arg: String
}

fn main() {
    use clap::Parser as _;
    Cli::parse();
}

Steps to reproduce the bug with the above code

cargo run

Actual Behaviour

output:

Usage: testclap [OPTIONS]

Options:
  -a <ARG>    do some job
              
              the job is print hello world [default: hello]
  -h, --help  Print help

Expected Behaviour

Usage: testclap [OPTIONS]

Options:
  -a <ARG>
          do some job
          
          the job is print hello world
          
          [default: hello]

  -h, --help
          Print help (see a summary with '-h')

Additional Context

code with help set with doc comment

#[derive(clap::Parser)]
struct Cli {
    /// do some job
    ///
    /// the job is print hello world
    #[arg(
        short,
        default_value = "hello",
    )]
    arg: String
}

fn main() {
    use clap::Parser as _;
    Cli::parse();
}

why not just use doc comment? i have to use attribute for localized help messages - with fl! macro

Debug Output

output with help set with #[arg(help = "...")]:

[clap_builder::builder::command]Command::_do_parse
[clap_builder::builder::command]Command::_build: name="testclap"
[clap_builder::builder::command]Command::_propagate:testclap
[clap_builder::builder::command]Command::_check_help_and_version:testclap expand_help_tree=false
[clap_builder::builder::command]Command::long_help_exists
[clap_builder::builder::command]Command::_check_help_and_version: Building default --help
[clap_builder::builder::command]Command::_propagate_global_args:testclap
[clap_builder::builder::debug_asserts]Command::_debug_asserts
[clap_builder::builder::debug_asserts]Arg::_debug_asserts:arg
[clap_builder::builder::debug_asserts]Arg::_debug_asserts:help
[clap_builder::builder::debug_asserts]Command::_verify_positionals
[clap_builder::parser::parser]Parser::get_matches_with
[clap_builder::parser::parser]Parser::parse
[clap_builder::parser::parser]Parser::get_matches_with: Begin parsing '"--help"'
[clap_builder::parser::parser]Parser::possible_subcommand: arg=Ok("--help")
[clap_builder::parser::parser]Parser::get_matches_with: sc=None
[clap_builder::parser::parser]Parser::parse_long_arg
[clap_builder::parser::parser]Parser::parse_long_arg: Does it contain '='...
[clap_builder::parser::parser]Parser::parse_long_arg: Found valid arg or flag '--help'
[clap_builder::parser::parser]Parser::parse_long_arg("help"): Presence validated
[clap_builder::parser::parser]Parser::react action=Help, identifier=Some(Long), source=CommandLine
[clap_builder::parser::parser]Help: use_long=true
[clap_builder::builder::command]Command::long_help_exists: false
[clap_builder::builder::command]Command::write_help_err: testclap, use_long=false
[clap_builder::builder::command]Command::long_help_exists: false
[  clap_builder::output::help]write_help
[clap_builder::output::help_template]HelpTemplate::new cmd=testclap, use_long=false
[clap_builder::output::help_template]should_show_arg: use_long=false, arg=arg
[clap_builder::output::help_template]HelpTemplate::write_templated_help
[clap_builder::output::help_template]HelpTemplate::write_before_help
[ clap_builder::output::usage]Usage::create_usage_no_title
[ clap_builder::output::usage]Usage::create_usage_no_title
[ clap_builder::output::usage]Usage::write_help_usage
[ clap_builder::output::usage]Usage::write_arg_usage; incl_reqs=true
[ clap_builder::output::usage]Usage::needs_options_tag
[ clap_builder::output::usage]Usage::needs_options_tag:iter: f=arg
[clap_builder::builder::command]Command::groups_for_arg: id="arg"
[ clap_builder::output::usage]Usage::needs_options_tag:iter:iter: grp_s="Cli"
[ clap_builder::output::usage]Usage::needs_options_tag:iter: [OPTIONS] required
[ clap_builder::output::usage]Usage::write_args: incls=[]
[ clap_builder::output::usage]Usage::get_args: unrolled_reqs=[]
[ clap_builder::output::usage]Usage::write_subcommand_usage
[ clap_builder::output::usage]Usage::create_usage_no_title: usage=testclap [OPTIONS]
[clap_builder::output::help_template]HelpTemplate::write_all_args
[clap_builder::output::help_template]should_show_arg: use_long=false, arg=arg
[clap_builder::output::help_template]should_show_arg: use_long=false, arg=help
[clap_builder::output::help_template]HelpTemplate::write_args Options
[clap_builder::output::help_template]should_show_arg: use_long=false, arg=arg
[clap_builder::output::help_template]HelpTemplate::write_args: arg="arg" longest=8
[clap_builder::output::help_template]should_show_arg: use_long=false, arg=help
[clap_builder::output::help_template]HelpTemplate::write_args: arg="help" longest=10
[clap_builder::output::help_template]should_show_arg: use_long=false, arg=arg
[clap_builder::output::help_template]HelpTemplate::spec_vals: a=-a <ARG>
[clap_builder::output::help_template]HelpTemplate::spec_vals: Found default value...[["hello"]]
[clap_builder::output::help_template]HelpTemplate::spec_vals: Found short aliases...[]
[clap_builder::output::help_template]HelpTemplate::spec_vals: Found aliases...[]
[clap_builder::output::help_template]should_show_arg: use_long=false, arg=help
[clap_builder::output::help_template]HelpTemplate::spec_vals: a=--help
[clap_builder::output::help_template]HelpTemplate::spec_vals: Found short aliases...[]
[clap_builder::output::help_template]HelpTemplate::spec_vals: Found aliases...[]
[clap_builder::output::help_template]HelpTemplate::spec_vals: a=-a <ARG>
[clap_builder::output::help_template]HelpTemplate::spec_vals: Found default value...[["hello"]]
[clap_builder::output::help_template]HelpTemplate::spec_vals: Found short aliases...[]
[clap_builder::output::help_template]HelpTemplate::spec_vals: Found aliases...[]
[clap_builder::output::help_template]HelpTemplate::short
[clap_builder::output::help_template]HelpTemplate::long
[clap_builder::output::help_template]HelpTemplate::align_to_about: arg=arg, next_line_help=false, longest=10
[clap_builder::output::help_template]HelpTemplate::align_to_about: positional=false arg_len=12, spaces=4
[clap_builder::output::help_template]HelpTemplate::help
[clap_builder::output::help_template]HelpTemplate::help: help_width=14, spaces=11, avail=86
[clap_builder::output::help_template]HelpTemplate::spec_vals: a=--help
[clap_builder::output::help_template]HelpTemplate::spec_vals: Found short aliases...[]
[clap_builder::output::help_template]HelpTemplate::spec_vals: Found aliases...[]
[clap_builder::output::help_template]HelpTemplate::short
[clap_builder::output::help_template]HelpTemplate::long
[clap_builder::output::help_template]HelpTemplate::align_to_about: arg=help, next_line_help=false, longest=10
[clap_builder::output::help_template]HelpTemplate::align_to_about: positional=false arg_len=10, spaces=2
[clap_builder::output::help_template]HelpTemplate::help
[clap_builder::output::help_template]HelpTemplate::help: help_width=14, spaces=10, avail=86
[clap_builder::output::help_template]HelpTemplate::write_after_help
[clap_builder::builder::command]Command::color: Color setting...
[clap_builder::builder::command]Auto
[clap_builder::builder::command]Command::color: Color setting...
[clap_builder::builder::command]Auto
Usage: testclap [OPTIONS]

Options:
  -a <ARG>    do some job
              
              the job is print hello world [default: hello]
  -h, --help  Print help

output with help set with doc comment

[clap_builder::builder::command]Command::_do_parse
[clap_builder::builder::command]Command::_build: name="testclap"
[clap_builder::builder::command]Command::_propagate:testclap
[clap_builder::builder::command]Command::_check_help_and_version:testclap expand_help_tree=false
[clap_builder::builder::command]Command::long_help_exists
[clap_builder::builder::command]Command::_check_help_and_version: Building default --help
[clap_builder::builder::command]Command::_propagate_global_args:testclap
[clap_builder::builder::debug_asserts]Command::_debug_asserts
[clap_builder::builder::debug_asserts]Arg::_debug_asserts:arg
[clap_builder::builder::debug_asserts]Arg::_debug_asserts:help
[clap_builder::builder::debug_asserts]Command::_verify_positionals
[clap_builder::parser::parser]Parser::get_matches_with
[clap_builder::parser::parser]Parser::parse
[clap_builder::parser::parser]Parser::get_matches_with: Begin parsing '"--help"'
[clap_builder::parser::parser]Parser::possible_subcommand: arg=Ok("--help")
[clap_builder::parser::parser]Parser::get_matches_with: sc=None
[clap_builder::parser::parser]Parser::parse_long_arg
[clap_builder::parser::parser]Parser::parse_long_arg: Does it contain '='...
[clap_builder::parser::parser]Parser::parse_long_arg: Found valid arg or flag '--help'
[clap_builder::parser::parser]Parser::parse_long_arg("help"): Presence validated
[clap_builder::parser::parser]Parser::react action=Help, identifier=Some(Long), source=CommandLine
[clap_builder::parser::parser]Help: use_long=true
[clap_builder::builder::command]Command::long_help_exists: true
[clap_builder::builder::command]Command::write_help_err: testclap, use_long=true
[clap_builder::builder::command]Command::long_help_exists: true
[  clap_builder::output::help]write_help
[clap_builder::output::help_template]HelpTemplate::new cmd=testclap, use_long=true
[clap_builder::output::help_template]should_show_arg: use_long=true, arg=arg
[clap_builder::output::help_template]HelpTemplate::write_templated_help
[clap_builder::output::help_template]HelpTemplate::write_before_help
[ clap_builder::output::usage]Usage::create_usage_no_title
[ clap_builder::output::usage]Usage::create_usage_no_title
[ clap_builder::output::usage]Usage::write_help_usage
[ clap_builder::output::usage]Usage::write_arg_usage; incl_reqs=true
[ clap_builder::output::usage]Usage::needs_options_tag
[ clap_builder::output::usage]Usage::needs_options_tag:iter: f=arg
[clap_builder::builder::command]Command::groups_for_arg: id="arg"
[ clap_builder::output::usage]Usage::needs_options_tag:iter:iter: grp_s="Cli"
[ clap_builder::output::usage]Usage::needs_options_tag:iter: [OPTIONS] required
[ clap_builder::output::usage]Usage::write_args: incls=[]
[ clap_builder::output::usage]Usage::get_args: unrolled_reqs=[]
[ clap_builder::output::usage]Usage::write_subcommand_usage
[ clap_builder::output::usage]Usage::create_usage_no_title: usage=testclap [OPTIONS]
[clap_builder::output::help_template]HelpTemplate::write_all_args
[clap_builder::output::help_template]should_show_arg: use_long=true, arg=arg
[clap_builder::output::help_template]should_show_arg: use_long=true, arg=help
[clap_builder::output::help_template]HelpTemplate::write_args Options
[clap_builder::output::help_template]should_show_arg: use_long=true, arg=arg
[clap_builder::output::help_template]HelpTemplate::write_args: arg="arg" longest=8
[clap_builder::output::help_template]should_show_arg: use_long=true, arg=help
[clap_builder::output::help_template]HelpTemplate::write_args: arg="help" longest=10
[clap_builder::output::help_template]should_show_arg: use_long=true, arg=arg
[clap_builder::output::help_template]HelpTemplate::spec_vals: a=-a <ARG>
[clap_builder::output::help_template]HelpTemplate::spec_vals: Found default value...[["hello"]]
[clap_builder::output::help_template]HelpTemplate::spec_vals: Found short aliases...[]
[clap_builder::output::help_template]HelpTemplate::spec_vals: Found aliases...[]
[clap_builder::output::help_template]HelpTemplate::spec_vals: a=-a <ARG>
[clap_builder::output::help_template]HelpTemplate::spec_vals: Found default value...[["hello"]]
[clap_builder::output::help_template]HelpTemplate::spec_vals: Found short aliases...[]
[clap_builder::output::help_template]HelpTemplate::spec_vals: Found aliases...[]
[clap_builder::output::help_template]HelpTemplate::short
[clap_builder::output::help_template]HelpTemplate::long
[clap_builder::output::help_template]HelpTemplate::align_to_about: arg=arg, next_line_help=true, longest=10
[clap_builder::output::help_template]HelpTemplate::align_to_about: printing long help so skip alignment
[clap_builder::output::help_template]HelpTemplate::help
[clap_builder::output::help_template]HelpTemplate::help: Next Line...true
[clap_builder::output::help_template]HelpTemplate::help: help_width=10, spaces=11, avail=90
[clap_builder::output::help_template]HelpTemplate::spec_vals: a=--help
[clap_builder::output::help_template]HelpTemplate::spec_vals: Found short aliases...[]
[clap_builder::output::help_template]HelpTemplate::spec_vals: Found aliases...[]
[clap_builder::output::help_template]HelpTemplate::short
[clap_builder::output::help_template]HelpTemplate::long
[clap_builder::output::help_template]HelpTemplate::align_to_about: arg=help, next_line_help=true, longest=10
[clap_builder::output::help_template]HelpTemplate::align_to_about: printing long help so skip alignment
[clap_builder::output::help_template]HelpTemplate::help
[clap_builder::output::help_template]HelpTemplate::help: Next Line...true
[clap_builder::output::help_template]HelpTemplate::help: help_width=10, spaces=36, avail=90
[clap_builder::output::help_template]HelpTemplate::write_after_help
[clap_builder::builder::command]Command::color: Color setting...
[clap_builder::builder::command]Auto
[clap_builder::builder::command]Command::color: Color setting...
[clap_builder::builder::command]Auto
Usage: testclap [OPTIONS]

Options:
  -a <ARG>
          do some job
          
          the job is print hello world
          
          [default: hello]

  -h, --help
          Print help (see a summary with '-h')

[epage]

Note that doc comments do not directly map to #[arg(help = "")] but are processed into #[arg(help = "")] and maybe also #[arg(long_help = "")], see https://docs.rs/clap/latest/clap/_derive/index.html#doc-comments

The long help view is only shown to the user when long help is configured in the application by using fields like long_help.