From 9866ea0ac5a92c7d2a7a21305a424b7c2ba82ea5 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Sun, 4 Apr 2021 20:02:32 -0400 Subject: [PATCH 1/2] rustdoc: Link to the docs on namespaces when an unknown disambiguator is found --- src/librustdoc/passes/collect_intra_doc_links.rs | 15 ++++++++++++++- .../intra-doc/email-address-localhost.stderr | 1 + .../intra-doc/unknown-disambiguator.stderr | 11 +++++++++++ 3 files changed, 26 insertions(+), 1 deletion(-) diff --git a/src/librustdoc/passes/collect_intra_doc_links.rs b/src/librustdoc/passes/collect_intra_doc_links.rs index 31e3c11c1b087..4be0e8823ee60 100644 --- a/src/librustdoc/passes/collect_intra_doc_links.rs +++ b/src/librustdoc/passes/collect_intra_doc_links.rs @@ -1924,7 +1924,20 @@ fn disambiguator_error( msg: &str, ) { diag_info.link_range = disambiguator_range; - report_diagnostic(cx.tcx, BROKEN_INTRA_DOC_LINKS, msg, &diag_info, |_diag, _sp| {}); + report_diagnostic(cx.tcx, BROKEN_INTRA_DOC_LINKS, msg, &diag_info, |diag, _sp| { + let channel = match env!("CFG_RELEASE_CHANNEL") { + "stable" => env!("CFG_RELEASE_NUM"), + "beta" => "beta", + "nightly" | "dev" => "nightly", + // custom build of rustdoc maybe? link to the stable docs just in case + _ => "", + }; + let msg = format!( + "see https://doc.rust-lang.org/{}/rustdoc/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators", + channel, + ); + diag.note(&msg); + }); } /// Report an ambiguity error, where there were multiple possible resolutions. diff --git a/src/test/rustdoc-ui/intra-doc/email-address-localhost.stderr b/src/test/rustdoc-ui/intra-doc/email-address-localhost.stderr index de215b2163bd4..f287f87408c48 100644 --- a/src/test/rustdoc-ui/intra-doc/email-address-localhost.stderr +++ b/src/test/rustdoc-ui/intra-doc/email-address-localhost.stderr @@ -10,6 +10,7 @@ note: the lint level is defined here LL | #![deny(warnings)] | ^^^^^^^^ = note: `#[deny(rustdoc::broken_intra_doc_links)]` implied by `#[deny(warnings)]` + = note: see https://doc.rust-lang.org/nightly/rustdoc/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators error: aborting due to previous error diff --git a/src/test/rustdoc-ui/intra-doc/unknown-disambiguator.stderr b/src/test/rustdoc-ui/intra-doc/unknown-disambiguator.stderr index 195aaca32a27d..94d6d4616518e 100644 --- a/src/test/rustdoc-ui/intra-doc/unknown-disambiguator.stderr +++ b/src/test/rustdoc-ui/intra-doc/unknown-disambiguator.stderr @@ -10,36 +10,47 @@ note: the lint level is defined here LL | #![deny(warnings)] | ^^^^^^^^ = note: `#[deny(rustdoc::broken_intra_doc_links)]` implied by `#[deny(warnings)]` + = note: see https://doc.rust-lang.org/nightly/rustdoc/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators error: unknown disambiguator `bar` --> $DIR/unknown-disambiguator.rs:3:35 | LL | //! Linking to [foo@banana] and [`bar@banana!()`]. | ^^^ + | + = note: see https://doc.rust-lang.org/nightly/rustdoc/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators error: unknown disambiguator `foo` --> $DIR/unknown-disambiguator.rs:9:34 | LL | //! And with weird backticks: [``foo@hello``] [foo`@`hello]. | ^^^ + | + = note: see https://doc.rust-lang.org/nightly/rustdoc/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators error: unknown disambiguator `foo` --> $DIR/unknown-disambiguator.rs:9:48 | LL | //! And with weird backticks: [``foo@hello``] [foo`@`hello]. | ^^^ + | + = note: see https://doc.rust-lang.org/nightly/rustdoc/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators error: unknown disambiguator `` --> $DIR/unknown-disambiguator.rs:6:31 | LL | //! And to [no disambiguator](@nectarine) and [another](@apricot!()). | ^ + | + = note: see https://doc.rust-lang.org/nightly/rustdoc/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators error: unknown disambiguator `` --> $DIR/unknown-disambiguator.rs:6:57 | LL | //! And to [no disambiguator](@nectarine) and [another](@apricot!()). | ^ + | + = note: see https://doc.rust-lang.org/nightly/rustdoc/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators error: aborting due to 6 previous errors From 3478f83c0adf65b05bd94310cd822ecefbaef105 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Tue, 6 Apr 2021 14:51:36 -0400 Subject: [PATCH 2/2] Reuse logic for determining the channel in the rest of rustdoc This doesn't update main.js because it's included as a fixed string. --- src/librustdoc/clean/types.rs | 12 +++--------- src/librustdoc/clean/utils.rs | 11 +++++++++++ src/librustdoc/core.rs | 9 ++++++--- src/librustdoc/lib.rs | 7 ++++++- src/librustdoc/passes/collect_intra_doc_links.rs | 12 +++--------- 5 files changed, 29 insertions(+), 22 deletions(-) diff --git a/src/librustdoc/clean/types.rs b/src/librustdoc/clean/types.rs index a5629fe1d1186..f3c9b987eb02a 100644 --- a/src/librustdoc/clean/types.rs +++ b/src/librustdoc/clean/types.rs @@ -16,7 +16,6 @@ use rustc_ast::{self as ast, AttrStyle}; use rustc_attr::{ConstStability, Deprecation, Stability, StabilityLevel}; use rustc_data_structures::fx::{FxHashMap, FxHashSet}; use rustc_data_structures::thin_vec::ThinVec; -use rustc_feature::UnstableFeatures; use rustc_hir as hir; use rustc_hir::def::{CtorKind, Res}; use rustc_hir::def_id::{CrateNum, DefId, DefIndex}; @@ -228,14 +227,9 @@ impl Item { "../".repeat(depth) } Some(&(_, _, ExternalLocation::Remote(ref s))) => s.to_string(), - Some(&(_, _, ExternalLocation::Unknown)) | None => String::from( - // NOTE: intentionally doesn't pass crate name to avoid having - // different primitive links between crates - if UnstableFeatures::from_environment(None).is_nightly_build() { - "https://doc.rust-lang.org/nightly" - } else { - "https://doc.rust-lang.org" - }, + Some(&(_, _, ExternalLocation::Unknown)) | None => format!( + "https://doc.rust-lang.org/{}", + crate::doc_rust_lang_org_channel(), ), }; // This is a primitive so the url is done "by hand". diff --git a/src/librustdoc/clean/utils.rs b/src/librustdoc/clean/utils.rs index 9c0ed1480fef3..1e79bd0912884 100644 --- a/src/librustdoc/clean/utils.rs +++ b/src/librustdoc/clean/utils.rs @@ -521,3 +521,14 @@ crate fn has_doc_flag(attrs: ty::Attributes<'_>, flag: Symbol) -> bool { && attr.meta_item_list().map_or(false, |l| rustc_attr::list_contains_name(&l, flag)) }) } + +/// Return a channel suitable for using in a `doc.rust-lang.org/{channel}` format string. +crate fn doc_rust_lang_org_channel() -> &'static str { + match env!("CFG_RELEASE_CHANNEL") { + "stable" => env!("CFG_RELEASE_NUM"), + "beta" => "beta", + "nightly" | "dev" => "nightly", + // custom build of rustdoc maybe? link to the stable docs just in case + _ => "", + } +} diff --git a/src/librustdoc/core.rs b/src/librustdoc/core.rs index 152094684adf4..c9fdaa50534dd 100644 --- a/src/librustdoc/core.rs +++ b/src/librustdoc/core.rs @@ -498,15 +498,18 @@ crate fn run_global_ctxt( let mut krate = tcx.sess.time("clean_crate", || clean::krate(&mut ctxt)); if krate.module.doc_value().map(|d| d.is_empty()).unwrap_or(true) { - let help = "The following guide may be of use:\n\ - https://doc.rust-lang.org/nightly/rustdoc/how-to-write-documentation.html"; + let help = format!( + "The following guide may be of use:\n\ + https://doc.rust-lang.org/{}/rustdoc/how-to-write-documentation.html", + crate::doc_rust_lang_org_channel(), + ); tcx.struct_lint_node( crate::lint::MISSING_CRATE_LEVEL_DOCS, DocContext::as_local_hir_id(tcx, krate.module.def_id).unwrap(), |lint| { let mut diag = lint.build("no documentation found for this crate's top-level module"); - diag.help(help); + diag.help(&help); diag.emit(); }, ); diff --git a/src/librustdoc/lib.rs b/src/librustdoc/lib.rs index 241aa1f12df7e..b9c4bbdceb276 100644 --- a/src/librustdoc/lib.rs +++ b/src/librustdoc/lib.rs @@ -82,6 +82,8 @@ use rustc_session::config::{make_crate_type_option, ErrorOutputType, RustcOptGro use rustc_session::getopts; use rustc_session::{early_error, early_warn}; +use crate::clean::utils::doc_rust_lang_org_channel; + /// A macro to create a FxHashMap. /// /// Example: @@ -597,7 +599,10 @@ fn usage(argv0: &str) { } println!("{}", options.usage(&format!("{} [options] ", argv0))); println!(" @path Read newline separated options from `path`\n"); - println!("More information available at https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html") + println!( + "More information available at https://doc.rust-lang.org/{}/rustdoc/what-is-rustdoc.html", + doc_rust_lang_org_channel() + ); } /// A result type used by several functions under `main()`. diff --git a/src/librustdoc/passes/collect_intra_doc_links.rs b/src/librustdoc/passes/collect_intra_doc_links.rs index 4be0e8823ee60..4bc7544e33d1e 100644 --- a/src/librustdoc/passes/collect_intra_doc_links.rs +++ b/src/librustdoc/passes/collect_intra_doc_links.rs @@ -1925,16 +1925,10 @@ fn disambiguator_error( ) { diag_info.link_range = disambiguator_range; report_diagnostic(cx.tcx, BROKEN_INTRA_DOC_LINKS, msg, &diag_info, |diag, _sp| { - let channel = match env!("CFG_RELEASE_CHANNEL") { - "stable" => env!("CFG_RELEASE_NUM"), - "beta" => "beta", - "nightly" | "dev" => "nightly", - // custom build of rustdoc maybe? link to the stable docs just in case - _ => "", - }; let msg = format!( - "see https://doc.rust-lang.org/{}/rustdoc/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators", - channel, + "see https://doc.rust-lang.org/{}/rustdoc/linking-to-items-by-name.html#namespaces-and-disambiguators \ + for more info about disambiguators", + crate::doc_rust_lang_org_channel(), ); diag.note(&msg); });