epage
commented
2 years ago 
Sent here by @epage, issue happened in this piece of code in one of my projects.
Open epage opened 2 years ago
epage
commented
2 years ago
Sent here by @epage, issue happened in this piece of code in one of my projects.
epage
commented
2 years ago
Now try deleting the empty comment "///\n". Does not appear anymore
Which empty comment?
epage
commented
2 years ago
(first step)
// Ouch commands:
// - `compress`
// - `decompress`
// - `list`
//
// Clap commands:
// - `help`
/// Repository: https://github.com/ouch-org/ouch(second step)
/// Ouch commands:
/// - `compress`
/// - `decompress`
/// - `list`
///
/// Clap commands:
/// - `help`
/// Repository: https://github.com/ouch-org/ouch@epage then you delete that "///" blank line at the middle, leaving this:
(third step)
/// Ouch commands:
/// - `compress`
/// - `decompress`
/// - `list`
/// Clap commands:
/// - `help`
/// Repository: https://github.com/ouch-org/ouchSorry for the confusion, this bug has too many steps to reproduce, maybe I even reported more than one bug at the same time.
epage
commented
2 years ago
Ok, let's break down all of the parts
about, which is why the blank line is importantlong_about and the last about wins, which is from the Cargo.toml in this caselong_about but nothing after it overrides it, so it winsflatten and subcommand would not cause us to pull in their doc comments (see https://github.com/clap-rs/clap/issues/2894)Ok, I think I covered it all
The challenge is in solutions because we can't introspect across items
long_about but we do some conditional logic based on if long_about is used anywhere. We'd have to dig in to see what the consequences would behelp_heading, we could allow users to set long_about (and more) to default. clap_derive could do this wherever it currently only sets about.epage
commented
2 years ago
Looks like if we always set long_about, it'll just cause long help to show up in errors, which seems pretty easy to do
fn help_err(&self, mut use_long: bool) -> ClapError {
debug!(
"Parser::help_err: use_long={:?}",
use_long && self.use_long_help()
);
use_long = use_long && self.use_long_help();
...
}
...
fn use_long_help(&self) -> bool {
debug!("Parser::use_long_help");
// In this case, both must be checked. This allows the retention of
// original formatting, but also ensures that the actual -h or --help
// specified by the user is sent through. If HiddenShortHelp is not included,
// then items specified with hidden_short_help will also be hidden.
let should_long = |v: &Arg| {
v.long_about.is_some()
|| v.is_set(ArgSettings::HiddenLongHelp)
|| v.is_set(ArgSettings::HiddenShortHelp)
};
self.app.long_about.is_some()
|| self.app.before_long_help.is_some()
|| self.app.after_long_help.is_some()
|| self.app.args.args().any(should_long)
|| self.app.subcommands.iter().any(|s| s.long_about.is_some())
}&& is important, it means we will only do this if something else is also requesting long helplong_about being set to about is the long help cases (like --help) we'll have the about on the next line rather than doing them all same-line with alignment
This might be a good enough workaround until we can get a better solution.
Please complete the following tasks
Rust Version
rustc 1.58.0-nightly (e249ce6b2 2021-10-30)
Clap Version
3.0.0-beta.5
Minimal reproducible code
Steps to reproduce the bug with the above code
cargo run -q -- --helpActual Behaviour
This is a tricky one, if you copy my code example, here is the --help message:
So, that
Repositoryline does not appear in the help message :-1:, but if we change all the//comments to be///(to three slashes):Now it appears!! :+1:.
Now try deleting the empty comment
"///\n". Does not appear anymore :-1:. Now you delete the#[clap(version, about)]line. Appears again :+1:.So, we went :-1: -> :+1: -> :-1: -> :+1: just by making small random changes.
Expected Behaviour
I assume it should be consistent and always show that repository line.
Additional Context
No response
Debug Output
With the starter code: