foster/denoland-deno
1
0
Fork 0
mirror of https://github.com/denoland/deno.git synced 2024-12-22 07:14:47 -05:00
Code Issues Packages 1 Wiki Activity

refactor: improve help text (#14249)

Browse source
This commit is contained in:
Ryan Dahl 2022-04-11 01:01:02 -04:00 committed by GitHub
parent 8ae17026cb
commit 1892612438
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 68 additions and 71 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

139
cli/flags.rs
View file

@ -467,9 +467,9 @@ static ENV_VARIABLES_HELP: &str = r#"ENVIRONMENT VARIABLES:
hostnames to use when fetching remote modules from hostnames to use when fetching remote modules from
private repositories private repositories
(e.g. "abcde12345@deno.land;54321edcba@github.com") (e.g. "abcde12345@deno.land;54321edcba@github.com")
DENO_TLS_CA_STORE Comma-separated list of order dependent certificate stores DENO_TLS_CA_STORE Comma-separated list of order dependent certificate
(system, mozilla) stores. Possible values: "system", "mozilla".
(defaults to mozilla) Defaults to "mozilla".
DENO_CERT Load certificate authority from PEM encoded file DENO_CERT Load certificate authority from PEM encoded file
DENO_DIR Set the cache directory DENO_DIR Set the cache directory
DENO_INSTALL_ROOT Set deno install's output directory DENO_INSTALL_ROOT Set deno install's output directory
@ -573,8 +573,7 @@ fn clap_root(version: &str) -> Command {
clap::Command::new("deno") clap::Command::new("deno")
.bin_name("deno") .bin_name("deno")
.color(ColorChoice::Never) .color(ColorChoice::Never)
// Disable clap's auto-detection of terminal width .max_term_width(80)
.term_width(0)
.version(version) .version(version)
.long_version(LONG_VERSION.as_str()) .long_version(LONG_VERSION.as_str())
.arg( .arg(
@ -588,6 +587,7 @@ fn clap_root(version: &str) -> Command {
.short('L') .short('L')
.long("log-level") .long("log-level")
.help("Set log level") .help("Set log level")
.hide(true)
.takes_value(true) .takes_value(true)
.possible_values(&["debug", "info"]) .possible_values(&["debug", "info"])
.global(true), .global(true),
@ -597,11 +597,6 @@ fn clap_root(version: &str) -> Command {
.short('q') .short('q')
.long("quiet") .long("quiet")
.help("Suppress diagnostic output") .help("Suppress diagnostic output")
.long_help(
"Suppress diagnostic output
By default, subcommands print human-readable diagnostic messages to stderr.
If the flag is set, restrict these messages to errors.",
)
.global(true), .global(true),
) )
.subcommand(bench_subcommand()) .subcommand(bench_subcommand())
@ -662,13 +657,13 @@ fn bench_subcommand<'a>() -> Command<'a> {
.long_about( .long_about(
"Run benchmarks using Deno's built-in bench tool. "Run benchmarks using Deno's built-in bench tool.
Evaluate the given modules, run all benches declared with 'Deno.bench()' and Evaluate the given modules, run all benches declared with 'Deno.bench()' \
report results to standard output: and report results to standard output:
deno bench src/fetch_bench.ts src/signal_bench.ts deno bench src/fetch_bench.ts src/signal_bench.ts
Directory arguments are expanded to all contained files matching the glob Directory arguments are expanded to all contained files matching the \
{*_,*.,}bench.{js,mjs,ts,jsx,tsx}: glob {*_,*.,}bench.{js,mjs,ts,jsx,tsx}:
deno bench src/", deno bench src/",
) )
@ -715,12 +710,12 @@ fn cache_subcommand<'a>() -> Command<'a> {
.long_about( .long_about(
"Cache and compile remote dependencies recursively. "Cache and compile remote dependencies recursively.
Download and compile a module with all of its static dependencies and save them Download and compile a module with all of its static dependencies and save \
in the local cache, without running any code: them in the local cache, without running any code:
deno cache https://deno.land/std/http/file_server.ts deno cache https://deno.land/std/http/file_server.ts
Future runs of this module will trigger no downloads or compilation unless Future runs of this module will trigger no downloads or compilation unless \
--reload is specified.", --reload is specified.",
) )
} }
@ -752,46 +747,48 @@ Unless --reload is specified, this command will not re-download already cached d
fn compile_subcommand<'a>() -> Command<'a> { fn compile_subcommand<'a>() -> Command<'a> {
runtime_args(Command::new("compile"), true, false) runtime_args(Command::new("compile"), true, false)
.trailing_var_arg(true) .trailing_var_arg(true)
.arg( .arg(script_arg().required(true))
script_arg().required(true),
)
.arg( .arg(
Arg::new("output") Arg::new("output")
.long("output") .long("output")
.short('o') .short('o')
.help("Output file (defaults to $PWD/<inferred-name>)") .help("Output file (defaults to $PWD/<inferred-name>)")
.takes_value(true) .takes_value(true)
.value_hint(ValueHint::FilePath) .value_hint(ValueHint::FilePath),
) )
.arg( .arg(
Arg::new("target") Arg::new("target")
.long("target") .long("target")
.help("Target OS architecture") .help("Target OS architecture")
.takes_value(true) .takes_value(true)
.possible_values(&["x86_64-unknown-linux-gnu", "x86_64-pc-windows-msvc", "x86_64-apple-darwin", "aarch64-apple-darwin"]) .possible_values(&[
"x86_64-unknown-linux-gnu",
"x86_64-pc-windows-msvc",
"x86_64-apple-darwin",
"aarch64-apple-darwin",
]),
) )
.about("UNSTABLE: Compile the script into a self contained executable") .about("UNSTABLE: Compile the script into a self contained executable")
.long_about( .long_about(
"UNSTABLE: Compiles the given script into a self contained executable. "UNSTABLE: Compiles the given script into a self contained executable.
deno compile -A https://deno.land/std/http/file_server.ts deno compile -A https://deno.land/std/http/file_server.ts
deno compile --output /usr/local/bin/color_util https://deno.land/std/examples/colors.ts deno compile --output color_util https://deno.land/std/examples/colors.ts
Any flags passed which affect runtime behavior, such as '--unstable', Any flags passed which affect runtime behavior, such as '--unstable', \
'--allow-*', '--v8-flags', etc. are encoded into the output executable and used '--allow-*', '--v8-flags', etc. are encoded into the output executable and \
at runtime as if they were passed to a similar 'deno run' command. used at runtime as if they were passed to a similar 'deno run' command.
The executable name is inferred by default: The executable name is inferred by default: Attempt to take the file stem of \
- Attempt to take the file stem of the URL path. The above example would the URL path. The above example would become 'file_server'. If the file stem \
become 'file_server'. is something generic like 'main', 'mod', 'index' or 'cli', and the path has no \
- If the file stem is something generic like 'main', 'mod', 'index' or 'cli', parent, take the file name of the parent path. Otherwise settle with the \
and the path has no parent, take the file name of the parent path. Otherwise generic name. If the resulting name has an '@...' suffix, strip it.
settle with the generic name.
- If the resulting name has an '@...' suffix, strip it.
This commands supports cross-compiling to different target architectures using `--target` flag. Cross-compiling to different target architectures is supported using the \
On the first invocation with deno will download proper binary and cache it in $DENO_DIR. The `--target` flag. On the first invocation with deno will download proper \
aarch64-apple-darwin target is not supported in canary. binary and cache it in $DENO_DIR. The aarch64-apple-darwin target is not \
supported in canary.
", ",
) )
} }
@ -835,8 +832,9 @@ Exclude urls ending with test.ts and test.js:
deno coverage --exclude=\"test\\.(ts|js)\" cov_profile deno coverage --exclude=\"test\\.(ts|js)\" cov_profile
Include urls that start with the file schema and exclude files ending with test.ts and test.js, for Include urls that start with the file schema and exclude files ending with \
an url to match it must match the include pattern and not match the exclude pattern: test.ts and test.js, for an url to match it must match the include pattern and \
not match the exclude pattern:
deno coverage --include=\"^file:\" --exclude=\"test\\.(ts|js)\" cov_profile deno coverage --include=\"^file:\" --exclude=\"test\\.(ts|js)\" cov_profile
@ -886,19 +884,20 @@ Generate html reports from lcov:
.help("Output coverage report in lcov format") .help("Output coverage report in lcov format")
.takes_value(false), .takes_value(false),
) )
.arg(Arg::new("output") .arg(
.requires("lcov") Arg::new("output")
.long("output") .requires("lcov")
.help("Output file (defaults to stdout) for lcov") .long("output")
.long_help("Exports the coverage report in lcov format to the given file. .help("Output file (defaults to stdout) for lcov")
Filename should be passed along with '=' .long_help(
For example '--output=foo.lcov' "Exports the coverage report in lcov format to the given file. \
If no --output arg is specified then the report is written to stdout." Filename should be passed along with '=' For example '--output=foo.lcov' \
) If no --output arg is specified then the report is written to stdout.",
.takes_value(true) )
.require_equals(true) .takes_value(true)
.value_hint(ValueHint::FilePath) .require_equals(true)
) .value_hint(ValueHint::FilePath),
)
.arg( .arg(
Arg::new("files") Arg::new("files")
.takes_value(true) .takes_value(true)
@ -1398,7 +1397,7 @@ Grant permission to read allow-listed files from disk:
deno run --allow-read=/etc https://deno.land/std/http/file_server.ts deno run --allow-read=/etc https://deno.land/std/http/file_server.ts
Deno allows specifying the filename '-' to read the file from stdin. Specifying the filename '-' to read the file from stdin.
curl https://deno.land/std/examples/welcome.ts | deno run -", curl https://deno.land/std/examples/welcome.ts | deno run -",
) )
@ -1759,7 +1758,7 @@ fn permission_args(app: Command) -> Command {
.long("allow-all") .long("allow-all")
.help("Allow all permissions"), .help("Allow all permissions"),
) )
.arg(Arg::new("prompt").long("prompt").help( .arg(Arg::new("prompt").long("prompt").hide(true).help(
"deprecated: Fallback to prompt if required permission wasn't passed", "deprecated: Fallback to prompt if required permission wasn't passed",
)) ))
.arg( .arg(
@ -1910,14 +1909,15 @@ fn v8_flags_arg<'a>() -> Arg<'a> {
.takes_value(true) .takes_value(true)
.use_value_delimiter(true) .use_value_delimiter(true)
.require_equals(true) .require_equals(true)
.help("Set V8 command line options (for help: --v8-flags=--help)") .help("Set V8 command line options")
.long_help("To see a list of all available flags use --v8-flags=--help.")
} }
fn seed_arg<'a>() -> Arg<'a> { fn seed_arg<'a>() -> Arg<'a> {
Arg::new("seed") Arg::new("seed")
.long("seed") .long("seed")
.value_name("NUMBER") .value_name("NUMBER")
.help("Seed Math.random()") .help("Set the random number generator seed")
.takes_value(true) .takes_value(true)
.validator(|val| match val.parse::<u64>() { .validator(|val| match val.parse::<u64>() {
Ok(_) => Ok(()), Ok(_) => Ok(()),
@ -1929,13 +1929,14 @@ fn compat_arg<'a>() -> Arg<'a> {
Arg::new("compat") Arg::new("compat")
.long("compat") .long("compat")
.requires("unstable") .requires("unstable")
.help("Node compatibility mode. Currently only enables built-in node modules like 'fs' and globals like 'process'.") .help("UNSTABLE: Node compatibility mode.")
.long_help("See https://deno.land/manual/node/compatibility_mode")
} }
fn watch_arg<'a>(takes_files: bool) -> Arg<'a> { fn watch_arg<'a>(takes_files: bool) -> Arg<'a> {
let arg = Arg::new("watch") let arg = Arg::new("watch")
.long("watch") .long("watch")
.help("UNSTABLE: Watch for file changes and restart process automatically"); .help("UNSTABLE: Watch for file changes and restart automatically");
if takes_files { if takes_files {
arg arg
@ -1952,8 +1953,8 @@ Additional paths might be watched by passing them as arguments to this flag.",
.value_hint(ValueHint::AnyPath) .value_hint(ValueHint::AnyPath)
} else { } else {
arg.long_help( arg.long_help(
"UNSTABLE: Watch for file changes and restart process automatically. "UNSTABLE: Watch for file changes and restart process automatically. \
Only local files from entry point module graph are watched.", Only local files from entry point module graph are watched.",
) )
} }
} }
@ -1974,9 +1975,8 @@ fn no_check_arg<'a>() -> Arg<'a> {
.long("no-check") .long("no-check")
.help("Skip type checking modules") .help("Skip type checking modules")
.long_help( .long_help(
"Skip type checking of modules. "Skip type-checking. If the value of '--no-check=remote' is supplied, \
If the value of '--no-check=remote' is supplied, diagnostic errors from remote diagnostic errors from remote modules will be ignored.",
modules will be ignored.",
) )
} }
@ -2036,16 +2036,13 @@ fn config_arg<'a>() -> Arg<'a> {
.short('c') .short('c')
.long("config") .long("config")
.value_name("FILE") .value_name("FILE")
.help("Load configuration file") .help("Specify the configuration file")
.long_help( .long_help(
"Load configuration file. "The configuration file can be used to configure different aspects of \
Before 1.14 Deno only supported loading tsconfig.json that allowed deno including TypeScript, linting, and code formatting. Typically the \
to customise TypeScript compiler settings. configuration file will be called `deno.json` or `deno.jsonc` and \
automatically detected; in that case this flag is not necessary. \
Starting with 1.14 configuration file can be used to configure different See https://deno.land/manual/getting_started/configuration_file",
subcommands like `deno lint` or `deno fmt`.
It's recommended to use `deno.json` or `deno.jsonc` as a filename.",
) )
.takes_value(true) .takes_value(true)
.value_hint(ValueHint::FilePath) .value_hint(ValueHint::FilePath)