From 8699a2dc6c5f3d71289c34bb388871db6120eacc Mon Sep 17 00:00:00 2001 From: Martin Pool Date: Mon, 15 Jan 2024 15:25:46 -0800 Subject: [PATCH] Help sections in clap --help --- src/main.rs | 101 +++++++++++++++++++++++++++++++--------------------- 1 file changed, 61 insertions(+), 40 deletions(-) diff --git a/src/main.rs b/src/main.rs index 336b692e..73c6b0ed 100644 --- a/src/main.rs +++ b/src/main.rs @@ -105,36 +105,41 @@ pub enum BaselineStrategy { )] struct Args { /// show cargo output for all invocations (very verbose). - #[arg(long)] + #[arg(long, help_heading = "Output")] all_logs: bool, /// baseline strategy: check that tests pass in an unmutated tree before testing mutants. - #[arg(long, value_enum, default_value_t = BaselineStrategy::Run)] + #[arg(long, value_enum, default_value_t = BaselineStrategy::Run, help_heading = "Execution")] baseline: BaselineStrategy, /// print mutants that were caught by tests. - #[arg(long, short = 'v')] + #[arg(long, short = 'v', help_heading = "Output")] caught: bool, /// cargo check generated mutants, but don't run tests. - #[arg(long)] + #[arg(long, help_heading = "Execution")] check: bool, - /// generate autocompletions for the given shell. - #[arg(long)] - completions: Option, - /// show the mutation diffs. - #[arg(long)] + #[arg(long, help_heading = "Filters")] diff: bool, /// rust crate directory to examine. - #[arg(long, short = 'd', conflicts_with = "manifest_path")] + #[arg( + long, + short = 'd', + conflicts_with = "manifest_path", + help_heading = "Input" + )] dir: Option, + /// generate autocompletions for the given shell. + #[arg(long)] + completions: Option, + /// return this error values from functions returning Result: /// for example, `::anyhow::anyhow!("mutated")`. - #[arg(long)] + #[arg(long, help_heading = "Generate")] error: Vec, /// regex for mutations to examine, matched against the names shown by `--list`. @@ -143,38 +148,44 @@ struct Args { short = 'F', alias = "regex", alias = "examine-regex", - alias = "examine-re" + alias = "examine-re", + help_heading = "Filters" )] examine_re: Vec, /// glob for files to exclude; with no glob, all files are included; globs containing /// slash match the entire path. If used together with `--file` argument, then the files to be examined are matched before the files to be excluded. - #[arg(long, short = 'e')] + #[arg(long, short = 'e', help_heading = "Filters")] exclude: Vec, /// regex for mutations to exclude, matched against the names shown by `--list`. - #[arg(long, short = 'E', alias = "exclude-regex")] + #[arg(long, short = 'E', alias = "exclude-regex", help_heading = "Filters")] exclude_re: Vec, /// glob for files to examine; with no glob, all files are examined; globs containing /// slash match the entire path. If used together with `--exclude` argument, then the files to be examined are matched before the files to be excluded. - #[arg(long, short = 'f')] + #[arg(long, short = 'f', help_heading = "Filters")] file: Vec, /// don't copy files matching gitignore patterns. - #[arg(long, action = ArgAction::Set, default_value = "true")] + #[arg(long, action = ArgAction::Set, default_value = "true", help_heading = "Copying")] gitignore: bool, /// run this many cargo build/test jobs in parallel. - #[arg(long, short = 'j', env = "CARGO_MUTANTS_JOBS")] + #[arg( + long, + short = 'j', + env = "CARGO_MUTANTS_JOBS", + help_heading = "Execution" + )] jobs: Option, /// output json (only for --list). - #[arg(long)] + #[arg(long, help_heading = "Output")] json: bool, /// don't delete the scratch directories, for debugging. - #[arg(long)] + #[arg(long, help_heading = "Debug")] leak_dirs: bool, /// log level for stdout (trace, debug, info, warn, error). @@ -182,76 +193,81 @@ struct Args { long, short = 'L', default_value = "info", - env = "CARGO_MUTANTS_TRACE_LEVEL" + env = "CARGO_MUTANTS_TRACE_LEVEL", + help_heading = "Debug" )] level: tracing::Level, /// just list possible mutants, don't run them. - #[arg(long)] + #[arg(long, help_heading = "Execution")] list: bool, /// list source files, don't run anything. - #[arg(long)] + #[arg(long, help_heading = "Execution")] list_files: bool, /// path to Cargo.toml for the package to mutate. - #[arg(long)] + #[arg(long, help_heading = "Input")] manifest_path: Option, /// don't read .cargo/mutants.toml. - #[arg(long)] + #[arg(long, help_heading = "Input")] no_config: bool, /// don't copy the /target directory, and don't build the source tree first. - #[arg(long)] + #[arg(long, help_heading = "Copying")] no_copy_target: bool, /// don't print times or tree sizes, to make output deterministic. - #[arg(long)] + #[arg(long, help_heading = "Output")] no_times: bool, /// include line & column numbers in the mutation list. - #[arg(long, action = ArgAction::Set, default_value = "true")] + #[arg(long, action = ArgAction::Set, default_value = "true", help_heading = "Output")] line_col: bool, /// create mutants.out within this directory. - #[arg(long, short = 'o')] + #[arg(long, short = 'o', help_heading = "Output")] output: Option, /// include only mutants in code touched by this diff. - #[arg(long, short = 'D')] + #[arg(long, short = 'D', help_heading = "Filters")] in_diff: Option, /// minimum timeout for tests, in seconds, as a lower bound on the auto-set time. - #[arg(long, env = "CARGO_MUTANTS_MINIMUM_TEST_TIMEOUT")] + #[arg( + long, + env = "CARGO_MUTANTS_MINIMUM_TEST_TIMEOUT", + help_heading = "Execution" + )] minimum_test_timeout: Option, /// only test mutants from these packages. - #[arg(id = "package", long, short = 'p')] + #[arg(id = "package", long, short = 'p', help_heading = "Filters")] mutate_packages: Vec, /// run mutants in random order. - #[arg(long)] + #[arg(long, help_heading = "Execution")] shuffle: bool, /// run mutants in the fixed order they occur in the source tree. - #[arg(long)] + #[arg(long, help_heading = "Execution")] no_shuffle: bool, /// run only one shard of all generated mutants: specify as e.g. 1/4. - #[arg(long)] + #[arg(long, help_heading = "Execution")] shard: Option, /// tool used to run test suites: cargo or nextest. - #[arg(long)] + #[arg(long, help_heading = "Execution")] test_tool: Option, /// maximum run time for all cargo commands, in seconds. - #[arg(long, short = 't')] + #[arg(long, short = 't', help_heading = "Execution")] timeout: Option, /// print mutations that failed to check or build. - #[arg(long, short = 'V')] + #[arg(long, short = 'V', help_heading = "Output")] unviable: bool, /// show version and quit. @@ -259,17 +275,22 @@ struct Args { version: bool, /// test every package in the workspace. - #[arg(long)] + #[arg(long, help_heading = "Filters")] workspace: bool, /// additional args for all cargo invocations. - #[arg(long, short = 'C', allow_hyphen_values = true)] + #[arg( + long, + short = 'C', + allow_hyphen_values = true, + help_heading = "Execution" + )] cargo_arg: Vec, // The following option captures all the remaining non-option args, to // send to cargo. /// pass remaining arguments to cargo test after all options and after `--`. - #[arg(last = true)] + #[arg(last = true, help_heading = "Execution")] cargo_test_args: Vec, }