Simplify command-line-argument declarations in librustdoc

This commit is contained in:
Zalathar 2024-11-07 23:27:20 +11:00
parent 001013c63c
commit b8377e5844
2 changed files with 463 additions and 472 deletions

View File

@ -1411,20 +1411,6 @@ pub fn is_stable(&self) -> bool {
pub fn apply(&self, options: &mut getopts::Options) { pub fn apply(&self, options: &mut getopts::Options) {
(self.apply)(options); (self.apply)(options);
} }
pub fn stable<F>(name: &'static str, f: F) -> RustcOptGroup
where
F: Fn(&mut getopts::Options) -> &mut getopts::Options + 'static,
{
RustcOptGroup { name, apply: Box::new(f), stability: OptionStability::Stable }
}
pub fn unstable<F>(name: &'static str, f: F) -> RustcOptGroup
where
F: Fn(&mut getopts::Options) -> &mut getopts::Options + 'static,
{
RustcOptGroup { name, apply: Box::new(f), stability: OptionStability::Unstable }
}
} }
pub fn make_opt( pub fn make_opt(

View File

@ -215,470 +215,475 @@ fn init_logging(early_dcx: &EarlyDiagCtxt) {
} }
fn opts() -> Vec<RustcOptGroup> { fn opts() -> Vec<RustcOptGroup> {
let stable: fn(_, fn(&mut getopts::Options) -> &mut _) -> _ = RustcOptGroup::stable; use rustc_session::config::OptionKind::{Flag, FlagMulti, Multi, Opt};
let unstable: fn(_, fn(&mut getopts::Options) -> &mut _) -> _ = RustcOptGroup::unstable; use rustc_session::config::OptionStability::{Stable, Unstable};
use rustc_session::config::make_opt as opt;
vec![ vec![
stable("h", |o| o.optflagmulti("h", "help", "show this help message")), opt(Stable, FlagMulti, "h", "help", "show this help message", ""),
stable("V", |o| o.optflagmulti("V", "version", "print rustdoc's version")), opt(Stable, FlagMulti, "V", "version", "print rustdoc's version", ""),
stable("v", |o| o.optflagmulti("v", "verbose", "use verbose output")), opt(Stable, FlagMulti, "v", "verbose", "use verbose output", ""),
stable("w", |o| o.optopt("w", "output-format", "the output type to write", "[html]")), opt(Stable, Opt, "w", "output-format", "the output type to write", "[html]"),
stable("output", |o| { opt(
o.optopt( Stable,
"", Opt,
"output", "",
"Which directory to place the output. \ "output",
This option is deprecated, use --out-dir instead.", "Which directory to place the output. This option is deprecated, use --out-dir instead.",
"PATH", "PATH",
) ),
}), opt(Stable, Opt, "o", "out-dir", "which directory to place the output", "PATH"),
stable("o", |o| o.optopt("o", "out-dir", "which directory to place the output", "PATH")), opt(Stable, Opt, "", "crate-name", "specify the name of this crate", "NAME"),
stable("crate-name", |o| {
o.optopt("", "crate-name", "specify the name of this crate", "NAME")
}),
make_crate_type_option(), make_crate_type_option(),
stable("L", |o| { opt(Stable, Multi, "L", "library-path", "directory to add to crate search path", "DIR"),
o.optmulti("L", "library-path", "directory to add to crate search path", "DIR") opt(Stable, Multi, "", "cfg", "pass a --cfg to rustc", ""),
}), opt(Stable, Multi, "", "check-cfg", "pass a --check-cfg to rustc", ""),
stable("cfg", |o| o.optmulti("", "cfg", "pass a --cfg to rustc", "")), opt(Stable, Multi, "", "extern", "pass an --extern to rustc", "NAME[=PATH]"),
stable("check-cfg", |o| o.optmulti("", "check-cfg", "pass a --check-cfg to rustc", "")), opt(
stable("extern", |o| o.optmulti("", "extern", "pass an --extern to rustc", "NAME[=PATH]")), Unstable,
unstable("extern-html-root-url", |o| { Multi,
o.optmulti( "",
"", "extern-html-root-url",
"extern-html-root-url", "base URL to use for dependencies; for example, \
"base URL to use for dependencies; for example, \ \"std=/doc\" links std::vec::Vec to /doc/std/vec/struct.Vec.html",
\"std=/doc\" links std::vec::Vec to /doc/std/vec/struct.Vec.html", "NAME=URL",
"NAME=URL", ),
) opt(
}), Unstable,
unstable("extern-html-root-takes-precedence", |o| { FlagMulti,
o.optflagmulti( "",
"", "extern-html-root-takes-precedence",
"extern-html-root-takes-precedence", "give precedence to `--extern-html-root-url`, not `html_root_url`",
"give precedence to `--extern-html-root-url`, not `html_root_url`", "",
) ),
}), opt(Stable, Multi, "C", "codegen", "pass a codegen option to rustc", "OPT[=VALUE]"),
stable("C", |o| { opt(Stable, FlagMulti, "", "document-private-items", "document private items", ""),
o.optmulti("C", "codegen", "pass a codegen option to rustc", "OPT[=VALUE]") opt(
}), Unstable,
stable("document-private-items", |o| { FlagMulti,
o.optflagmulti("", "document-private-items", "document private items") "",
}), "document-hidden-items",
unstable("document-hidden-items", |o| { "document items that have doc(hidden)",
o.optflagmulti("", "document-hidden-items", "document items that have doc(hidden)") "",
}), ),
stable("test", |o| o.optflagmulti("", "test", "run code examples as tests")), opt(Stable, FlagMulti, "", "test", "run code examples as tests", ""),
stable("test-args", |o| { opt(Stable, Multi, "", "test-args", "arguments to pass to the test runner", "ARGS"),
o.optmulti("", "test-args", "arguments to pass to the test runner", "ARGS") opt(
}), Stable,
stable("test-run-directory", |o| { Opt,
o.optopt( "",
"", "test-run-directory",
"test-run-directory", "The working directory in which to run tests",
"The working directory in which to run tests", "PATH",
"PATH", ),
) opt(Stable, Opt, "", "target", "target triple to document", "TRIPLE"),
}), opt(
stable("target", |o| o.optopt("", "target", "target triple to document", "TRIPLE")), Stable,
stable("markdown-css", |o| { Multi,
o.optmulti( "",
"", "markdown-css",
"markdown-css", "CSS files to include via <link> in a rendered Markdown file",
"CSS files to include via <link> in a rendered Markdown file", "FILES",
"FILES", ),
) opt(
}), Stable,
stable("html-in-header", |o| { Multi,
o.optmulti( "",
"", "html-in-header",
"html-in-header", "files to include inline in the <head> section of a rendered Markdown file \
"files to include inline in the <head> section of a rendered Markdown file \ or generated documentation",
or generated documentation", "FILES",
"FILES", ),
) opt(
}), Stable,
stable("html-before-content", |o| { Multi,
o.optmulti( "",
"", "html-before-content",
"html-before-content", "files to include inline between <body> and the content of a rendered \
"files to include inline between <body> and the content of a rendered \ Markdown file or generated documentation",
Markdown file or generated documentation", "FILES",
"FILES", ),
) opt(
}), Stable,
stable("html-after-content", |o| { Multi,
o.optmulti( "",
"", "html-after-content",
"html-after-content", "files to include inline between the content and </body> of a rendered \
"files to include inline between the content and </body> of a rendered \ Markdown file or generated documentation",
Markdown file or generated documentation", "FILES",
"FILES", ),
) opt(
}), Unstable,
unstable("markdown-before-content", |o| { Multi,
o.optmulti( "",
"", "markdown-before-content",
"markdown-before-content", "files to include inline between <body> and the content of a rendered \
"files to include inline between <body> and the content of a rendered \ Markdown file or generated documentation",
Markdown file or generated documentation", "FILES",
"FILES", ),
) opt(
}), Unstable,
unstable("markdown-after-content", |o| { Multi,
o.optmulti( "",
"", "markdown-after-content",
"markdown-after-content", "files to include inline between the content and </body> of a rendered \
"files to include inline between the content and </body> of a rendered \ Markdown file or generated documentation",
Markdown file or generated documentation", "FILES",
"FILES", ),
) opt(Stable, Opt, "", "markdown-playground-url", "URL to send code snippets to", "URL"),
}), opt(Stable, FlagMulti, "", "markdown-no-toc", "don't include table of contents", ""),
stable("markdown-playground-url", |o| { opt(
o.optopt("", "markdown-playground-url", "URL to send code snippets to", "URL") Stable,
}), Opt,
stable("markdown-no-toc", |o| { "e",
o.optflagmulti("", "markdown-no-toc", "don't include table of contents") "extend-css",
}), "To add some CSS rules with a given file to generate doc with your own theme. \
stable("e", |o| { However, your theme might break if the rustdoc's generated HTML changes, so be careful!",
o.optopt( "PATH",
"e", ),
"extend-css", opt(
"To add some CSS rules with a given file to generate doc with your \ Unstable,
own theme. However, your theme might break if the rustdoc's generated HTML \ Multi,
changes, so be careful!", "Z",
"PATH", "",
) "unstable / perma-unstable options (only on nightly build)",
}), "FLAG",
unstable("Z", |o| { ),
o.optmulti("Z", "", "unstable / perma-unstable options (only on nightly build)", "FLAG") opt(Stable, Opt, "", "sysroot", "Override the system root", "PATH"),
}), opt(
stable("sysroot", |o| o.optopt("", "sysroot", "Override the system root", "PATH")), Unstable,
unstable("playground-url", |o| { Opt,
o.optopt( "",
"", "playground-url",
"playground-url", "URL to send code snippets to, may be reset by --markdown-playground-url \
"URL to send code snippets to, may be reset by --markdown-playground-url \ or `#![doc(html_playground_url=...)]`",
or `#![doc(html_playground_url=...)]`", "URL",
"URL", ),
) opt(
}), Unstable,
unstable("display-doctest-warnings", |o| { FlagMulti,
o.optflagmulti( "",
"", "display-doctest-warnings",
"display-doctest-warnings", "show warnings that originate in doctests",
"show warnings that originate in doctests", "",
) ),
}), opt(
stable("crate-version", |o| { Stable,
o.optopt("", "crate-version", "crate version to print into documentation", "VERSION") Opt,
}), "",
unstable("sort-modules-by-appearance", |o| { "crate-version",
o.optflagmulti( "crate version to print into documentation",
"", "VERSION",
"sort-modules-by-appearance", ),
"sort modules by where they appear in the program, rather than alphabetically", opt(
) Unstable,
}), FlagMulti,
stable("default-theme", |o| { "",
o.optopt( "sort-modules-by-appearance",
"", "sort modules by where they appear in the program, rather than alphabetically",
"default-theme", "",
"Set the default theme. THEME should be the theme name, generally lowercase. \ ),
If an unknown default theme is specified, the builtin default is used. \ opt(
The set of themes, and the rustdoc built-in default, are not stable.", Stable,
"THEME", Opt,
) "",
}), "default-theme",
unstable("default-setting", |o| { "Set the default theme. THEME should be the theme name, generally lowercase. \
o.optmulti( If an unknown default theme is specified, the builtin default is used. \
"", The set of themes, and the rustdoc built-in default, are not stable.",
"default-setting", "THEME",
"Default value for a rustdoc setting (used when \"rustdoc-SETTING\" is absent \ ),
from web browser Local Storage). If VALUE is not supplied, \"true\" is used. \ opt(
Supported SETTINGs and VALUEs are not documented and not stable.", Unstable,
"SETTING[=VALUE]", Multi,
) "",
}), "default-setting",
stable("theme", |o| { "Default value for a rustdoc setting (used when \"rustdoc-SETTING\" is absent \
o.optmulti( from web browser Local Storage). If VALUE is not supplied, \"true\" is used. \
"", Supported SETTINGs and VALUEs are not documented and not stable.",
"theme", "SETTING[=VALUE]",
"additional themes which will be added to the generated docs", ),
"FILES", opt(
) Stable,
}), Multi,
stable("check-theme", |o| { "",
o.optmulti("", "check-theme", "check if given theme is valid", "FILES") "theme",
}), "additional themes which will be added to the generated docs",
unstable("resource-suffix", |o| { "FILES",
o.optopt( ),
"", opt(Stable, Multi, "", "check-theme", "check if given theme is valid", "FILES"),
"resource-suffix", opt(
"suffix to add to CSS and JavaScript files, e.g., \"search-index.js\" will \ Unstable,
become \"search-index-suffix.js\"", Opt,
"PATH", "",
) "resource-suffix",
}), "suffix to add to CSS and JavaScript files, \
stable("edition", |o| { e.g., \"search-index.js\" will become \"search-index-suffix.js\"",
o.optopt( "PATH",
"", ),
"edition", opt(
"edition to use when compiling rust code (default: 2015)", Stable,
"EDITION", Opt,
) "",
}), "edition",
stable("color", |o| { "edition to use when compiling rust code (default: 2015)",
o.optopt( "EDITION",
"", ),
"color", opt(
"Configure coloring of output: Stable,
Opt,
"",
"color",
"Configure coloring of output:
auto = colorize, if output goes to a tty (default); auto = colorize, if output goes to a tty (default);
always = always colorize output; always = always colorize output;
never = never colorize output", never = never colorize output",
"auto|always|never", "auto|always|never",
) ),
}), opt(
stable("error-format", |o| { Stable,
o.optopt( Opt,
"", "",
"error-format", "error-format",
"How errors and other messages are produced", "How errors and other messages are produced",
"human|json|short", "human|json|short",
) ),
}), opt(
stable("diagnostic-width", |o| { Stable,
o.optopt( Opt,
"", "",
"diagnostic-width", "diagnostic-width",
"Provide width of the output for truncated error messages", "Provide width of the output for truncated error messages",
"WIDTH", "WIDTH",
) ),
}), opt(Stable, Opt, "", "json", "Configure the structure of JSON diagnostics", "CONFIG"),
stable("json", |o| { opt(Stable, Multi, "A", "allow", "Set lint allowed", "LINT"),
o.optopt("", "json", "Configure the structure of JSON diagnostics", "CONFIG") opt(Stable, Multi, "W", "warn", "Set lint warnings", "LINT"),
}), opt(Stable, Multi, "", "force-warn", "Set lint force-warn", "LINT"),
stable("allow", |o| o.optmulti("A", "allow", "Set lint allowed", "LINT")), opt(Stable, Multi, "D", "deny", "Set lint denied", "LINT"),
stable("warn", |o| o.optmulti("W", "warn", "Set lint warnings", "LINT")), opt(Stable, Multi, "F", "forbid", "Set lint forbidden", "LINT"),
stable("force-warn", |o| o.optmulti("", "force-warn", "Set lint force-warn", "LINT")), opt(
stable("deny", |o| o.optmulti("D", "deny", "Set lint denied", "LINT")), Stable,
stable("forbid", |o| o.optmulti("F", "forbid", "Set lint forbidden", "LINT")), Multi,
stable("cap-lints", |o| { "",
o.optmulti( "cap-lints",
"", "Set the most restrictive lint level. \
"cap-lints", More restrictive lints are capped at this level. \
"Set the most restrictive lint level. \ By default, it is at `forbid` level.",
More restrictive lints are capped at this \ "LEVEL",
level. By default, it is at `forbid` level.", ),
"LEVEL", opt(Unstable, Opt, "", "index-page", "Markdown file to be used as index page", "PATH"),
) opt(
}), Unstable,
unstable("index-page", |o| { FlagMulti,
o.optopt("", "index-page", "Markdown file to be used as index page", "PATH") "",
}), "enable-index-page",
unstable("enable-index-page", |o| { "To enable generation of the index page",
o.optflagmulti("", "enable-index-page", "To enable generation of the index page") "",
}), ),
unstable("static-root-path", |o| { opt(
o.optopt( Unstable,
"", Opt,
"static-root-path", "",
"Path string to force loading static files from in output pages. \ "static-root-path",
If not set, uses combinations of '../' to reach the documentation root.", "Path string to force loading static files from in output pages. \
"PATH", If not set, uses combinations of '../' to reach the documentation root.",
) "PATH",
}), ),
unstable("persist-doctests", |o| { opt(
o.optopt( Unstable,
"", Opt,
"persist-doctests", "",
"Directory to persist doctest executables into", "persist-doctests",
"PATH", "Directory to persist doctest executables into",
) "PATH",
}), ),
unstable("show-coverage", |o| { opt(
o.optflagmulti( Unstable,
"", FlagMulti,
"show-coverage", "",
"calculate percentage of public items with documentation", "show-coverage",
) "calculate percentage of public items with documentation",
}), "",
unstable("enable-per-target-ignores", |o| { ),
o.optflagmulti( opt(
"", Unstable,
"enable-per-target-ignores", FlagMulti,
"parse ignore-foo for ignoring doctests on a per-target basis", "",
) "enable-per-target-ignores",
}), "parse ignore-foo for ignoring doctests on a per-target basis",
unstable("runtool", |o| { "",
o.optopt( ),
"", opt(
"runtool", Unstable,
"", Opt,
"The tool to run tests with when building for a different target than host", "",
) "runtool",
}), "",
unstable("runtool-arg", |o| { "The tool to run tests with when building for a different target than host",
o.optmulti( ),
"", opt(
"runtool-arg", Unstable,
"", Multi,
"One (of possibly many) arguments to pass to the runtool", "",
) "runtool-arg",
}), "",
unstable("test-builder", |o| { "One (of possibly many) arguments to pass to the runtool",
o.optopt("", "test-builder", "The rustc-like binary to use as the test builder", "PATH") ),
}), opt(
unstable("test-builder-wrapper", |o| { Unstable,
o.optmulti( Opt,
"", "",
"test-builder-wrapper", "test-builder",
"Wrapper program to pass test-builder and arguments", "The rustc-like binary to use as the test builder",
"PATH", "PATH",
) ),
}), opt(
unstable("check", |o| o.optflagmulti("", "check", "Run rustdoc checks")), Unstable,
unstable("generate-redirect-map", |o| { Multi,
o.optflagmulti( "",
"", "test-builder-wrapper",
"generate-redirect-map", "Wrapper program to pass test-builder and arguments",
"Generate JSON file at the top level instead of generating HTML redirection files", "PATH",
) ),
}), opt(Unstable, FlagMulti, "", "check", "Run rustdoc checks", ""),
unstable("emit", |o| { opt(
o.optmulti( Unstable,
"", FlagMulti,
"emit", "",
"Comma separated list of types of output for rustdoc to emit", "generate-redirect-map",
"[unversioned-shared-resources,toolchain-shared-resources,invocation-specific]", "Generate JSON file at the top level instead of generating HTML redirection files",
) "",
}), ),
unstable("no-run", |o| { opt(
o.optflagmulti("", "no-run", "Compile doctests without running them") Unstable,
}), Multi,
unstable("remap-path-prefix", |o| { "",
o.optmulti( "emit",
"", "Comma separated list of types of output for rustdoc to emit",
"remap-path-prefix", "[unversioned-shared-resources,toolchain-shared-resources,invocation-specific]",
"Remap source names in compiler messages", ),
"FROM=TO", opt(Unstable, FlagMulti, "", "no-run", "Compile doctests without running them", ""),
) opt(
}), Unstable,
unstable("show-type-layout", |o| { Multi,
o.optflagmulti("", "show-type-layout", "Include the memory layout of types in the docs") "",
}), "remap-path-prefix",
unstable("nocapture", |o| { "Remap source names in compiler messages",
o.optflag("", "nocapture", "Don't capture stdout and stderr of tests") "FROM=TO",
}), ),
unstable("generate-link-to-definition", |o| { opt(
o.optflag( Unstable,
"", FlagMulti,
"generate-link-to-definition", "",
"Make the identifiers in the HTML source code pages navigable", "show-type-layout",
) "Include the memory layout of types in the docs",
}), "",
unstable("scrape-examples-output-path", |o| { ),
o.optopt( opt(Unstable, Flag, "", "nocapture", "Don't capture stdout and stderr of tests", ""),
"", opt(
"scrape-examples-output-path", Unstable,
"", Flag,
"collect function call information and output at the given path", "",
) "generate-link-to-definition",
}), "Make the identifiers in the HTML source code pages navigable",
unstable("scrape-examples-target-crate", |o| { "",
o.optmulti( ),
"", opt(
"scrape-examples-target-crate", Unstable,
"", Opt,
"collect function call information for functions from the target crate", "",
) "scrape-examples-output-path",
}), "",
unstable("scrape-tests", |o| { "collect function call information and output at the given path",
o.optflag("", "scrape-tests", "Include test code when scraping examples") ),
}), opt(
unstable("with-examples", |o| { Unstable,
o.optmulti( Multi,
"", "",
"with-examples", "scrape-examples-target-crate",
"", "",
"path to function call information (for displaying examples in the documentation)", "collect function call information for functions from the target crate",
) ),
}), opt(Unstable, Flag, "", "scrape-tests", "Include test code when scraping examples", ""),
unstable("merge", |o| { opt(
o.optopt( Unstable,
"", Multi,
"merge", "",
"Controls how rustdoc handles files from previously documented crates in the doc root "with-examples",
none = Do not write cross-crate information to the --out-dir "",
shared = Append current crate's info to files found in the --out-dir "path to function call information (for displaying examples in the documentation)",
finalize = Write current crate's info and --include-parts-dir info to the --out-dir, overwriting conflicting files", ),
"none|shared|finalize", opt(
) Unstable,
}), Opt,
unstable("parts-out-dir", |o| { "",
o.optopt( "merge",
"", "Controls how rustdoc handles files from previously documented crates in the doc root\n\
"parts-out-dir", none = Do not write cross-crate information to the --out-dir\n\
"Writes trait implementations and other info for the current crate to provided path. Only use with --merge=none", shared = Append current crate's info to files found in the --out-dir\n\
"path/to/doc.parts/<crate-name>", finalize = Write current crate's info and --include-parts-dir info to the --out-dir, overwriting conflicting files",
) "none|shared|finalize",
}), ),
unstable("include-parts-dir", |o| { opt(
o.optmulti( Unstable,
"", Opt,
"include-parts-dir", "",
"Includes trait implementations and other crate info from provided path. Only use with --merge=finalize", "parts-out-dir",
"path/to/doc.parts/<crate-name>", "Writes trait implementations and other info for the current crate to provided path. Only use with --merge=none",
) "path/to/doc.parts/<crate-name>",
}), ),
opt(
Unstable,
Multi,
"",
"include-parts-dir",
"Includes trait implementations and other crate info from provided path. Only use with --merge=finalize",
"path/to/doc.parts/<crate-name>",
),
// deprecated / removed options // deprecated / removed options
unstable("disable-minification", |o| o.optflagmulti("", "disable-minification", "removed")), opt(Unstable, FlagMulti, "", "disable-minification", "removed", ""),
stable("plugin-path", |o| { opt(
o.optmulti( Stable,
"", Multi,
"plugin-path", "",
"removed, see issue #44136 <https://github.com/rust-lang/rust/issues/44136> \ "plugin-path",
for more information", "removed, see issue #44136 <https://github.com/rust-lang/rust/issues/44136> for more information",
"DIR", "DIR",
) ),
}), opt(
stable("passes", |o| { Stable,
o.optmulti( Multi,
"", "",
"passes", "passes",
"removed, see issue #44136 <https://github.com/rust-lang/rust/issues/44136> \ "removed, see issue #44136 <https://github.com/rust-lang/rust/issues/44136> for more information",
for more information", "PASSES",
"PASSES", ),
) opt(
}), Stable,
stable("plugins", |o| { Multi,
o.optmulti( "",
"", "plugins",
"plugins", "removed, see issue #44136 <https://github.com/rust-lang/rust/issues/44136> for more information",
"removed, see issue #44136 <https://github.com/rust-lang/rust/issues/44136> \ "PLUGINS",
for more information", ),
"PLUGINS", opt(
) Stable,
}), FlagMulti,
stable("no-default", |o| { "",
o.optflagmulti( "no-defaults",
"", "removed, see issue #44136 <https://github.com/rust-lang/rust/issues/44136> for more information",
"no-defaults", "",
"removed, see issue #44136 <https://github.com/rust-lang/rust/issues/44136> \ ),
for more information", opt(
) Stable,
}), Opt,
stable("r", |o| { "r",
o.optopt( "input-format",
"r", "removed, see issue #44136 <https://github.com/rust-lang/rust/issues/44136> for more information",
"input-format", "[rust]",
"removed, see issue #44136 <https://github.com/rust-lang/rust/issues/44136> \ ),
for more information", opt(Unstable, Flag, "", "html-no-source", "Disable HTML source code pages generation", ""),
"[rust]",
)
}),
unstable("html-no-source", |o| {
o.optflag("", "html-no-source", "Disable HTML source code pages generation")
}),
] ]
} }