fix(rustdoc): always use a channel when linking to doc.rust-lang.org

rust-lang · jieyouxu · Dec 27, 2024 · Dec 26, 2024 · Jan 30, 2025 · Jan 21, 2025
commit a063cf5f1c151873f753905c75d8e67115308f9d
diff --git a/src/librustdoc/clean/mod.rs b/src/librustdoc/clean/mod.rs
@@ -1934,7 +1934,7 @@ fn can_elide_trait_object_lifetime_bound<'tcx>(
     preds: &'tcx ty::List<ty::PolyExistentialPredicate<'tcx>>,
     tcx: TyCtxt<'tcx>,
 ) -> bool {
-    // Below we quote extracts from https://doc.rust-lang.org/reference/lifetime-elision.html#default-trait-object-lifetimes
+    // Below we quote extracts from https://doc.rust-lang.org/stable/reference/lifetime-elision.html#default-trait-object-lifetimes
 
     // > If the trait object is used as a type argument of a generic type then the containing type is
     // > first used to try to infer a bound.

diff --git a/src/librustdoc/clean/utils.rs b/src/librustdoc/clean/utils.rs
@@ -590,9 +590,9 @@ pub(crate) fn attrs_have_doc_flag<'a>(
 /// so that the channel is consistent.
 ///
 /// Set by `bootstrap::Builder::doc_rust_lang_org_channel` in order to keep tests passing on beta/stable.
-pub(crate) const DOC_RUST_LANG_ORG_CHANNEL: &str = env!("DOC_RUST_LANG_ORG_CHANNEL");
-pub(crate) static DOC_CHANNEL: Lazy<&'static str> =
-    Lazy::new(|| DOC_RUST_LANG_ORG_CHANNEL.rsplit('/').find(|c| !c.is_empty()).unwrap());
+pub(crate) const DOC_RUST_LANG_ORG_VERSION: &str = env!("DOC_RUST_LANG_ORG_CHANNEL");
+pub(crate) static RUSTDOC_VERSION: Lazy<&'static str> =
+    Lazy::new(|| DOC_RUST_LANG_ORG_VERSION.rsplit('/').find(|c| !c.is_empty()).unwrap());
 
 /// Render a sequence of macro arms in a format suitable for displaying to the user
 /// as part of an item declaration.

diff --git a/src/librustdoc/core.rs b/src/librustdoc/core.rs
@@ -387,7 +387,7 @@ pub(crate) fn run_global_ctxt(
         let help = format!(
             "The following guide may be of use:\n\
             {}/rustdoc/how-to-write-documentation.html",
-            crate::DOC_RUST_LANG_ORG_CHANNEL
+            crate::DOC_RUST_LANG_ORG_VERSION
         );
         tcx.node_lint(
             crate::lint::MISSING_CRATE_LEVEL_DOCS,

diff --git a/src/librustdoc/html/layout.rs b/src/librustdoc/html/layout.rs
@@ -112,7 +112,7 @@ pub(crate) fn render<T: Print, S: Print>(
         display_krate_with_trailing_slash,
         display_krate_version_number,
         display_krate_version_extra,
-        rust_channel: *crate::clean::utils::DOC_CHANNEL,
+        rust_channel: *crate::clean::utils::RUSTDOC_VERSION,
         rustdoc_version,
     }
     .render()

diff --git a/src/librustdoc/html/render/context.rs b/src/librustdoc/html/render/context.rs
@@ -32,7 +32,7 @@ use crate::html::render::write_shared::write_shared;
 use crate::html::url_parts_builder::UrlPartsBuilder;
 use crate::html::{layout, sources, static_files};
 use crate::scrape_examples::AllCallLocations;
-use crate::try_err;
+use crate::{DOC_RUST_LANG_ORG_VERSION, try_err};
 
 /// Major driving force in all rustdoc rendering. This contains information
 /// about where in the tree-like hierarchy rendering is occurring and controls
@@ -730,7 +730,7 @@ impl<'tcx> FormatRenderer<'tcx> for Context<'tcx> {
                          <noscript>\
                             <section>\
                                 <p>You need to enable JavaScript to use keyboard commands or search.</p>\
-                                <p>For more information, browse the <a href=\"https://doc.rust-lang.org/rustdoc/\">rustdoc handbook</a>.</p>\
+                                <p>For more information, browse the <a href=\"{DOC_RUST_LANG_ORG_VERSION}/rustdoc/\">rustdoc handbook</a>.</p>\
                             </section>\
                          </noscript>",
                     )

diff --git a/src/librustdoc/html/render/mod.rs b/src/librustdoc/html/render/mod.rs
@@ -79,7 +79,7 @@ use crate::html::markdown::{
 use crate::html::static_files::SCRAPE_EXAMPLES_HELP_MD;
 use crate::html::{highlight, sources};
 use crate::scrape_examples::{CallData, CallLocation};
-use crate::{DOC_RUST_LANG_ORG_CHANNEL, try_none};
+use crate::{DOC_RUST_LANG_ORG_VERSION, try_none};
 
 pub(crate) fn ensure_trailing_slash(v: &str) -> impl fmt::Display + '_ {
     fmt::from_fn(move |f| {
@@ -480,7 +480,7 @@ fn scrape_examples_help(shared: &SharedContext<'_>) -> String {
     content.push_str(&format!(
         "## More information\n\n\
       If you want more information about this feature, please read the [corresponding chapter in \
-      the Rustdoc book]({DOC_RUST_LANG_ORG_CHANNEL}/rustdoc/scraped-examples.html)."
+      the Rustdoc book]({DOC_RUST_LANG_ORG_VERSION}/rustdoc/scraped-examples.html)."
     ));
 
     let mut ids = IdMap::default();

diff --git a/src/librustdoc/html/render/print_item.rs b/src/librustdoc/html/render/print_item.rs
@@ -924,7 +924,7 @@ fn item_trait(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, t: &clean::Tra
                 <a href=\"{base}/reference/items/traits.html#dyn-compatibility\">dyn compatible</a>.</p>\
                 <p><i>In older versions of Rust, dyn compatibility was called \"object safety\", \
                 so this trait is not object safe.</i></p></div>",
-                base = crate::clean::utils::DOC_RUST_LANG_ORG_CHANNEL
+                base = crate::clean::utils::DOC_RUST_LANG_ORG_VERSION
             ),
         );
     }

diff --git a/src/librustdoc/html/static/js/main.js b/src/librustdoc/html/static/js/main.js
@@ -1534,10 +1534,10 @@ function preLoadCss(cssUrl) {
 
     function buildHelpMenu() {
         const book_info = document.createElement("span");
-        const channel = getVar("channel");
+        const drloChannel = `https://doc.rust-lang.org/${getVar("channel")}`;
         book_info.className = "top";
         book_info.innerHTML = `You can find more information in \
-<a href="https://doc.rust-lang.org/${channel}/rustdoc/">the rustdoc book</a>.`;
+<a href="${drloChannel}/rustdoc/">the rustdoc book</a>.`;
 
         const shortcuts = [
             ["?", "Show this help dialog"],
@@ -1557,8 +1557,8 @@ function preLoadCss(cssUrl) {
         div_shortcuts.innerHTML = "<h2>Keyboard Shortcuts</h2><dl>" + shortcuts + "</dl></div>";
 
         const infos = [
-            `For a full list of all search features, take a look <a \
-href="https://doc.rust-lang.org/${channel}/rustdoc/read-documentation/search.html">here</a>.`,
+            `For a full list of all search features, take a look \
+             <a href="${drloChannel}/rustdoc/read-documentation/search.html">here</a>.`,
             "Prefix searches with a type followed by a colon (e.g., <code>fn:</code>) to \
              restrict the search to a given item kind.",
             "Accepted kinds are: <code>fn</code>, <code>mod</code>, <code>struct</code>, \
@@ -1568,10 +1568,10 @@ href="https://doc.rust-lang.org/${channel}/rustdoc/read-documentation/search.htm
              <code>-&gt; vec</code> or <code>String, enum:Cow -&gt; bool</code>)",
             "You can look for items with an exact name by putting double quotes around \
              your request: <code>\"string\"</code>",
-             "Look for functions that accept or return \
-              <a href=\"https://doc.rust-lang.org/std/primitive.slice.html\">slices</a> and \
-              <a href=\"https://doc.rust-lang.org/std/primitive.array.html\">arrays</a> by writing \
-              square brackets (e.g., <code>-&gt; [u8]</code> or <code>[] -&gt; Option</code>)",
+             `Look for functions that accept or return \
+              <a href="${drloChannel}/std/primitive.slice.html">slices</a> and \
+              <a href="${drloChannel}/std/primitive.array.html">arrays</a> by writing square \
+              brackets (e.g., <code>-&gt; [u8]</code> or <code>[] -&gt; Option</code>)`,
             "Look for items inside another one by searching for a path: <code>vec::Vec</code>",
         ].map(x => "<p>" + x + "</p>").join("");
         const div_infos = document.createElement("div");

diff --git a/src/librustdoc/html/static/js/search.js b/src/librustdoc/html/static/js/search.js
@@ -1,5 +1,5 @@
 // ignore-tidy-filelength
-/* global addClass, getNakedUrl, getSettingValue */
+/* global addClass, getNakedUrl, getSettingValue, getVar */
 /* global onEachLazy, removeClass, searchState, browserSupportsHistoryApi, exports */
 
 "use strict";
@@ -4923,17 +4923,18 @@ ${item.displayPath}<span class="${type}">${name}</span>\
             }
         });
     } else if (query.error === null) {
+        const dlroChannel = `https://doc.rust-lang.org/${getVar("channel")}`;
         output.className = "search-failed" + extraClass;
         output.innerHTML = "No results :(<br/>" +
             "Try on <a href=\"https://duckduckgo.com/?q=" +
             encodeURIComponent("rust " + query.userQuery) +
             "\">DuckDuckGo</a>?<br/><br/>" +
             "Or try looking in one of these:<ul><li>The <a " +
-            "href=\"https://doc.rust-lang.org/reference/index.html\">Rust Reference</a> " +
+            `href="${dlroChannel}/reference/index.html">Rust Reference</a> ` +
             " for technical details about the language.</li><li><a " +
-            "href=\"https://doc.rust-lang.org/rust-by-example/index.html\">Rust By " +
+            `href="${dlroChannel}/rust-by-example/index.html">Rust By ` +
             "Example</a> for expository code examples.</a></li><li>The <a " +
-            "href=\"https://doc.rust-lang.org/book/index.html\">Rust Book</a> for " +
+            `href="${dlroChannel}/book/index.html">Rust Book</a> for ` +
             "introductions to language features and the language itself.</li><li><a " +
             "href=\"https://docs.rs\">Docs.rs</a> for documentation of crates released on" +
             " <a href=\"https://crates.io/\">crates.io</a>.</li></ul>";

diff --git a/src/librustdoc/html/templates/type_layout.html b/src/librustdoc/html/templates/type_layout.html
@@ -10,7 +10,7 @@ <h2 id="layout" class="section-header"> {# #}
                 unstable</strong> and may even differ between compilations. {#+ #}
             The only exception is types with certain <code>repr(...)</code> {#+ #}
             attributes. Please see the Rust Reference's {#+ #}
-            <a href="https://doc.rust-lang.org/reference/type-layout.html">“Type Layout”</a> {#+ #}
+            <a href="{{ crate::DOC_RUST_LANG_ORG_VERSION }}/reference/type-layout.html">“Type Layout”</a> {#+ #}
             chapter for details on type layout guarantees. {# #}
         </p> {# #}
     </div> {# #}

diff --git a/src/librustdoc/html/templates/type_layout_size.html b/src/librustdoc/html/templates/type_layout_size.html
@@ -7,6 +7,6 @@
     {{ size +}} bytes
   {% endif %}
   {% if is_uninhabited %}
-    {# +#} (<a href="https://doc.rust-lang.org/stable/reference/glossary.html#uninhabited">uninhabited</a>)
+    {# +#} (<a href="{{ crate::DOC_RUST_LANG_ORG_VERSION }}/reference/glossary.html#uninhabited">uninhabited</a>)
   {% endif %}
 {% endif %}
diff --git a/src/librustdoc/lib.rs b/src/librustdoc/lib.rs
@@ -82,7 +82,7 @@ use rustc_session::config::{ErrorOutputType, RustcOptGroup, make_crate_type_opti
 use rustc_session::{EarlyDiagCtxt, getopts};
 use tracing::info;
 
-use crate::clean::utils::DOC_RUST_LANG_ORG_CHANNEL;
+use crate::clean::utils::DOC_RUST_LANG_ORG_VERSION;
 
 /// A macro to create a FxHashMap.
 ///
@@ -710,7 +710,7 @@ fn usage(argv0: &str) {
     println!("{}", options.usage(&format!("{argv0} [options] <input>")));
     println!("    @path               Read newline separated options from `path`\n");
     println!(
-        "More information available at {DOC_RUST_LANG_ORG_CHANNEL}/rustdoc/what-is-rustdoc.html",
+        "More information available at {DOC_RUST_LANG_ORG_VERSION}/rustdoc/what-is-rustdoc.html",
     );
 }
 

diff --git a/src/librustdoc/passes/collect_intra_doc_links.rs b/src/librustdoc/passes/collect_intra_doc_links.rs
@@ -2168,7 +2168,7 @@ fn disambiguator_error(
     report_diagnostic(cx.tcx, BROKEN_INTRA_DOC_LINKS, msg, &diag_info, |diag, _sp, _link_range| {
         let msg = format!(
             "see {}/rustdoc/write-documentation/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators",
-            crate::DOC_RUST_LANG_ORG_CHANNEL
+            crate::DOC_RUST_LANG_ORG_VERSION
         );
         diag.note(msg);
     });

diff --git a/tests/rustdoc/type-layout.rs b/tests/rustdoc/type-layout.rs
@@ -86,11 +86,11 @@ pub enum WithNiche {
 }
 
 //@ hasraw type_layout/enum.Uninhabited.html 'Size: '
-//@ hasraw - '0 bytes (<a href="https://doc.rust-lang.org/stable/reference/glossary.html#uninhabited">uninhabited</a>)'
+//@ hasraw - '0 bytes (<a href="{{channel}}/reference/glossary.html#uninhabited">uninhabited</a>)'
 pub enum Uninhabited {}
 
 //@ hasraw type_layout/struct.Uninhabited2.html 'Size: '
-//@ hasraw - '8 bytes (<a href="https://doc.rust-lang.org/stable/reference/glossary.html#uninhabited">uninhabited</a>)'
+//@ hasraw - '8 bytes (<a href="{{channel}}/reference/glossary.html#uninhabited">uninhabited</a>)'
 pub struct Uninhabited2(std::convert::Infallible, u64);
 
 pub trait Project { type Assoc; }