Begin diagnostic translation migration for rustdoc

Author: cassaundra

compiler/rustc_error_messages/locales/en-US/rustdoc.ftl

@@ -0,0 +1,111 @@
+rustdoc_compilation_failed =
+    Compilation failed, aborting rustdoc
+
+rustdoc_couldnt_generate_documentation =
+    couldn't generate documentation: {$error}
+    .note = failed to create or modify "{$file}"
+
+rustdoc_missing_crate_level_docs =
+    no documentation found for this crate's top-level module
+    .help = The following guide may be of use:
+            {$doc_rust_lang_org_channel}/rustdoc/how-to-write-documentation.html
+
+rustdoc_deprecated_attr =
+    the `#![doc({$attr_name})]` attribute is deprecated
+    .note = see issue #44136 <https://github.com/rust-lang/rust/issues/44136> for more information
+
+rustdoc_deprecated_attr_no_default_passes =
+    `#![doc(no_default_passes)]` no longer functions; you may want to use `#![doc(document_private_items)]`
+
+rustdoc_deprecated_attr_passes =
+    `#![doc(passes = "...")]` no longer functions; you may want to use `#![doc(document_private_items)]`
+
+rustdoc_deprecated_attr_plugins =
+    `#![doc(plugins = "...")]` no longer functions; see CVE-2018-1000622 <https://nvd.nist.gov/vuln/detail/CVE-2018-1000622>
+
+rustdoc_could_not_resolve_path =
+    failed to resolve: could not resolve path `{$path}`
+    .label = could not resolve path `{$path}`
+    .note = this error was originally ignored because you are running `rustdoc`
+    .help = try running again with `rustc` or `cargo check` and you may get a more detailed error
+
+rustdoc_unrecognized_emission_type =
+    unrecognized emission type: {$kind}
+
+rustdoc_invalid_extern_html_root_url =
+    --extern-html-root-url must be of the form name=url
+
+rustdoc_missing_file_operand =
+    missing file operand
+
+rustdoc_too_many_file_operands =
+    too many file operands
+
+rustdoc_no_run_flag_without_test_flag =
+    the `--test` flag must be passed to enable `--no-run`
+
+rustdoc_cannot_use_out_dir_and_output_flags =
+    cannot use both 'out-dir' and 'output' at once
+
+rustdoc_option_extend_css_arg_not_file =
+    option --extend-css argument must be a file
+
+rustdoc_theme_arg_not_file =
+    invalid argument: "{$theme_arg}"
+    .help = arguments to --theme must be files
+
+rustdoc_theme_arg_not_css_file =
+    invalid argument: "{$theme_arg}"
+    .help = arguments to --theme must have a .css extension
+
+rustdoc_error_loading_theme_file =
+    error loading theme file: "{$theme_arg}"
+
+rustdoc_theme_file_missing_default_theme_css_rules =
+    theme file "{$theme_arg}" is missing CSS rules from the default theme
+    .warn = the theme may appear incorrect when loaded
+    .help = "to see what rules are missing, call `rustdoc --check-theme "{$theme_arg}"`
+
+rustdoc_unknown_input_format =
+    unkown input format: {$theme_arg}
+
+rustdoc_index_page_arg_not_file =
+    option `--index-page` argument must be a file
+
+rustdoc_unknown_crate_type =
+    unknown crate type: {$error}
+
+rustdoc_html_output_not_supported_with_show_coverage_flag =
+    html output format isn't supported for the --show-coverage option
+
+rustdoc_generate_link_to_definition_flag_not_with_html_output_format =
+    --generate-link-to-definition option can only be used with HTML output format
+
+rustdoc_scrape_examples_output_path_and_target_crate_not_used_together =
+    must use --scrape-examples-output-path and --scrape-examples-target-crate together
+
+rustdoc_scrape_tests_not_with_scrape_examples_output_path_and_target_crate =
+    must use --scrape-examples-output-path and --scrape-examples-target-crate with --scrape-tests
+
+rustdoc_flag_deprecated =
+    the `{$flag}` flag is deprecated
+    .note = see issue #44136 <https://github.com/rust-lang/rust/issues/44136> for more information
+
+rustdoc_flag_removed =
+    the `{$flag}` flag no longer functions
+    .note = see issue #44136 <https://github.com/rust-lang/rust/issues/44136> for more information
+
+rustdoc_use_document_private_items_flag =
+    you may want to use --document-private-items
+
+rustdoc_see_rustdoc_plugins_cve =
+    see CVE-2018-1000622
+
+rustdoc_error_reading_file =
+    error reading `{$file_path}`: {$error}
+
+rustdoc_error_reading_file_not_utf8 =
+    error reading `{$file_path}`: not UTF-8
+
+rustdoc_error_loading_examples =
+    failed to load examples: {$error} (for path {$path})

compiler/rustc_error_messages/src/lib.rs

@@ -66,6 +66,7 @@ fluent_messages! {
     privacy => "../locales/en-US/privacy.ftl",
     query_system => "../locales/en-US/query_system.ftl",
     resolve => "../locales/en-US/resolve.ftl",
+    rustdoc => "../locales/en-US/rustdoc.ftl",
     save_analysis => "../locales/en-US/save_analysis.ftl",
     session => "../locales/en-US/session.ftl",
     symbol_mangling => "../locales/en-US/symbol_mangling.ftl",

src/librustdoc/config.rs

@@ -7,6 +7,7 @@ use std::str::FromStr;
 
 use rustc_data_structures::fx::FxHashMap;
 use rustc_driver::print_flag_list;
+use rustc_errors::ErrorGuaranteed;
 use rustc_session::config::{
     self, parse_crate_types_from_list, parse_externs, parse_target_triple, CrateType,
 };
@@ -21,6 +22,14 @@ use rustc_span::edition::Edition;
 use rustc_target::spec::TargetTriple;
 
 use crate::core::new_handler;
+use crate::errors::{
+    CannotUseOutDirAndOutputFlags, ErrorLoadingThemeFile, ExtendCssArgNotFile, FlagDeprecated,
+    FlagRemoved, FlagRemovedSuggestion, GenerateLinkToDefinitionFlagNotWithHtmlOutputFormat,
+    HtmlOutputNotSupportedWithShowCoverageFlag, IndexPageArgNotFile, InvalidExternHtmlRootUrl,
+    MissingFileOperand, NoRunFlagWithoutTestFlag, ThemeArgNotCssFile, ThemeArgNotFile,
+    ThemeFileMissingDefaultThemeCssRules, TooManyFileOperands, UnknownCrateType,
+    UnknownInputFormat, UnrecognizedEmissionType,
+};
 use crate::externalfiles::ExternalHtml;
 use crate::html;
 use crate::html::markdown::IdMap;
@@ -396,7 +405,7 @@ impl Options {
                 match kind.parse() {
                     Ok(kind) => emit.push(kind),
                     Err(()) => {
-                        diag.err(&format!("unrecognized emission type: {}", kind));
+                        diag.emit_err(UnrecognizedEmissionType { kind });
                         return Err(1);
                     }
                 }
@@ -452,10 +461,10 @@ impl Options {
         let input = PathBuf::from(if describe_lints {
             "" // dummy, this won't be used
         } else if matches.free.is_empty() {
-            diag.struct_err("missing file operand").emit();
+            diag.emit_err(MissingFileOperand);
             return Err(1);
         } else if matches.free.len() > 1 {
-            diag.struct_err("too many file operands").emit();
+            diag.emit_err(TooManyFileOperands);
             return Err(1);
         } else {
             &matches.free[0]
@@ -467,13 +476,7 @@ impl Options {
             .map(|s| SearchPath::from_cli_opt(s, error_format))
             .collect();
         let externs = parse_externs(matches, &unstable_opts, error_format);
-        let extern_html_root_urls = match parse_extern_html_roots(matches) {
-            Ok(ex) => ex,
-            Err(err) => {
-                diag.struct_err(err).emit();
-                return Err(1);
-            }
-        };
+        let extern_html_root_urls = parse_extern_html_roots(matches, &diag).map_err(|_| 1)?;
 
         let default_settings: Vec<Vec<(String, String)>> = vec![
             matches
@@ -529,15 +532,15 @@ impl Options {
         let no_run = matches.opt_present("no-run");
 
         if !should_test && no_run {
-            diag.err("the `--test` flag must be passed to enable `--no-run`");
+            diag.emit_err(NoRunFlagWithoutTestFlag);
             return Err(1);
         }
 
         let out_dir = matches.opt_str("out-dir").map(|s| PathBuf::from(&s));
         let output = matches.opt_str("output").map(|s| PathBuf::from(&s));
         let output = match (out_dir, output) {
             (Some(_), Some(_)) => {
-                diag.struct_err("cannot use both 'out-dir' and 'output' at once").emit();
+                diag.emit_err(CannotUseOutDirAndOutputFlags);
                 return Err(1);
             }
             (Some(out_dir), None) => out_dir,
@@ -552,7 +555,7 @@ impl Options {
 
         if let Some(ref p) = extension_css {
             if !p.is_file() {
-                diag.struct_err("option --extend-css argument must be a file").emit();
+                diag.emit_err(ExtendCssArgNotFile);
                 return Err(1);
             }
         }
@@ -573,32 +576,19 @@ impl Options {
                 matches.opt_strs("theme").iter().map(|s| (PathBuf::from(&s), s.to_owned()))
             {
                 if !theme_file.is_file() {
-                    diag.struct_err(&format!("invalid argument: \"{}\"", theme_s))
-                        .help("arguments to --theme must be files")
-                        .emit();
+                    diag.emit_err(ThemeArgNotFile { theme_arg: &theme_s });
                     return Err(1);
                 }
                 if theme_file.extension() != Some(OsStr::new("css")) {
-                    diag.struct_err(&format!("invalid argument: \"{}\"", theme_s))
-                        .help("arguments to --theme must have a .css extension")
-                        .emit();
+                    diag.emit_err(ThemeArgNotCssFile { theme_arg: &theme_s });
                     return Err(1);
                 }
                 let (success, ret) = theme::test_theme_against(&theme_file, &paths, &diag);
                 if !success {
-                    diag.struct_err(&format!("error loading theme file: \"{}\"", theme_s)).emit();
+                    diag.emit_err(ErrorLoadingThemeFile { theme_arg: &theme_s });
                     return Err(1);
                 } else if !ret.is_empty() {
-                    diag.struct_warn(&format!(
-                        "theme file \"{}\" is missing CSS rules from the default theme",
-                        theme_s
-                    ))
-                    .warn("the theme may appear incorrect when loaded")
-                    .help(&format!(
-                        "to see what rules are missing, call `rustdoc --check-theme \"{}\"`",
-                        theme_s
-                    ))
-                    .emit();
+                    diag.emit_warning(ThemeFileMissingDefaultThemeCssRules { theme_arg: &theme_s });
                 }
                 themes.push(StylePath { path: theme_file });
             }
@@ -625,15 +615,15 @@ impl Options {
         match matches.opt_str("r").as_deref() {
             Some("rust") | None => {}
             Some(s) => {
-                diag.struct_err(&format!("unknown input format: {}", s)).emit();
+                diag.emit_err(UnknownInputFormat { input_format_arg: s });
                 return Err(1);
             }
         }
 
         let index_page = matches.opt_str("index-page").map(|s| PathBuf::from(&s));
         if let Some(ref index_page) = index_page {
             if !index_page.is_file() {
-                diag.struct_err("option `--index-page` argument must be a file").emit();
+                diag.emit_err(IndexPageArgNotFile);
                 return Err(1);
             }
         }
@@ -644,8 +634,8 @@ impl Options {
 
         let crate_types = match parse_crate_types_from_list(matches.opt_strs("crate-type")) {
             Ok(types) => types,
-            Err(e) => {
-                diag.struct_err(&format!("unknown crate type: {}", e)).emit();
+            Err(error) => {
+                diag.emit_err(UnknownCrateType { error });
                 return Err(1);
             }
         };
@@ -654,10 +644,7 @@ impl Options {
             Some(s) => match OutputFormat::try_from(s.as_str()) {
                 Ok(out_fmt) => {
                     if !out_fmt.is_json() && show_coverage {
-                        diag.struct_err(
-                            "html output format isn't supported for the --show-coverage option",
-                        )
-                        .emit();
+                        diag.emit_err(HtmlOutputNotSupportedWithShowCoverageFlag);
                         return Err(1);
                     }
                     out_fmt
@@ -707,10 +694,7 @@ impl Options {
             matches.opt_present("extern-html-root-takes-precedence");
 
         if generate_link_to_definition && (show_coverage || output_format != OutputFormat::Html) {
-            diag.struct_err(
-                "--generate-link-to-definition option can only be used with HTML output format",
-            )
-            .emit();
+            diag.emit_err(GenerateLinkToDefinitionFlagNotWithHtmlOutputFormat);
             return Err(1);
         }
 
@@ -804,32 +788,23 @@ fn check_deprecated_options(matches: &getopts::Matches, diag: &rustc_errors::Han
 
     for &flag in deprecated_flags.iter() {
         if matches.opt_present(flag) {
-            diag.struct_warn(&format!("the `{}` flag is deprecated", flag))
-                .note(
-                    "see issue #44136 <https://github.com/rust-lang/rust/issues/44136> \
-                    for more information",
-                )
-                .emit();
+            diag.emit_warning(FlagDeprecated { flag });
         }
     }
 
     let removed_flags = ["plugins", "plugin-path", "no-defaults", "passes", "input-format"];
 
     for &flag in removed_flags.iter() {
         if matches.opt_present(flag) {
-            let mut err = diag.struct_warn(&format!("the `{}` flag no longer functions", flag));
-            err.note(
-                "see issue #44136 <https://github.com/rust-lang/rust/issues/44136> \
-                for more information",
-            );
-
-            if flag == "no-defaults" || flag == "passes" {
-                err.help("you may want to use --document-private-items");
+            let suggestion = if flag == "no-defaults" || flag == "passes" {
+                Some(FlagRemovedSuggestion::DocumentPrivateItems)
             } else if flag == "plugins" || flag == "plugin-path" {
-                err.warn("see CVE-2018-1000622");
-            }
+                Some(FlagRemovedSuggestion::SeeRustdocPluginsCve)
+            } else {
+                None
+            };
 
-            err.emit();
+            diag.emit_warning(FlagRemoved { flag, suggestion });
         }
     }
 }
@@ -839,11 +814,12 @@ fn check_deprecated_options(matches: &getopts::Matches, diag: &rustc_errors::Han
 /// describing the issue.
 fn parse_extern_html_roots(
     matches: &getopts::Matches,
-) -> Result<BTreeMap<String, String>, &'static str> {
+    diag: &rustc_errors::Handler,
+) -> Result<BTreeMap<String, String>, ErrorGuaranteed> {
     let mut externs = BTreeMap::new();
     for arg in &matches.opt_strs("extern-html-root-url") {
         let (name, url) =
-            arg.split_once('=').ok_or("--extern-html-root-url must be of the form name=url")?;
+            arg.split_once('=').ok_or_else(|| diag.emit_err(InvalidExternHtmlRootUrl))?;
         externs.insert(name.to_string(), url.to_string());
     }
     Ok(externs)