Fix rustdoc warnings and add CI

Wilfred · Wilfred · commit 5c93137d2f8f · 2025-12-01T13:06:15.000Z
rustdoc has a separate environment variable for banning warnings, so set that in the GitHub action configuration. rust-lang/cargo#8424 (comment) Fix all the rustdoc warnings on unknown types or functions. I've updated references wherever it's obvious, otherwise I've replaced the rustdoc link with plain backticks. There were also some cases where rustdoc links referred to private APIs. I've disabled the rustdoc private API warning in those crates.
diff --git a/src/tools/rust-analyzer/.github/workflows/rustdoc.yaml b/src/tools/rust-analyzer/.github/workflows/rustdoc.yaml
@@ -8,6 +8,7 @@ env:
   CARGO_INCREMENTAL: 0
   CARGO_NET_RETRY: 10
   RUSTFLAGS: "-D warnings -W unreachable-pub"
+  RUSTDOCFLAGS: "-D warnings"
   RUSTUP_MAX_RETRIES: 10
 
 jobs:
diff --git a/src/tools/rust-analyzer/crates/hir-def/src/expr_store.rs b/src/tools/rust-analyzer/crates/hir-def/src/expr_store.rs
@@ -43,7 +43,7 @@ pub use self::lower::{
     hir_assoc_type_binding_to_ast, hir_generic_arg_to_ast, hir_segment_to_ast_segment,
 };
 
-/// A wrapper around [`span::SyntaxContextId`] that is intended only for comparisons.
+/// A wrapper around [`span::SyntaxContext`] that is intended only for comparisons.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct HygieneId(span::SyntaxContext);
 
diff --git a/src/tools/rust-analyzer/crates/hir-def/src/hir/generics.rs b/src/tools/rust-analyzer/crates/hir-def/src/hir/generics.rs
@@ -20,7 +20,7 @@ pub type LocalLifetimeParamId = Idx<LifetimeParamData>;
 /// Data about a generic type parameter (to a function, struct, impl, ...).
 #[derive(Clone, PartialEq, Eq, Debug, Hash)]
 pub struct TypeParamData {
-    /// [`None`] only if the type ref is an [`TypeRef::ImplTrait`]. FIXME: Might be better to just
+    /// [`None`] only if the type ref is an [`crate::type_ref::TypeRef::ImplTrait`]. FIXME: Might be better to just
     /// make it always be a value, giving impl trait a special name.
     pub name: Option<Name>,
     pub default: Option<TypeRefId>,
diff --git a/src/tools/rust-analyzer/crates/hir-def/src/lang_item.rs b/src/tools/rust-analyzer/crates/hir-def/src/lang_item.rs
@@ -234,7 +234,7 @@ language_item_table! { LangItems =>
     Clone,                   sym::clone,               clone_trait,                TraitId,                GenericRequirement::None;
     Sync,                    sym::sync,                sync_trait,                 TraitId,                GenericRequirement::Exact(0);
     DiscriminantKind,        sym::discriminant_kind,   discriminant_kind_trait,    TraitId,                GenericRequirement::None;
-    /// The associated item of the [`DiscriminantKind`] trait.
+    /// The associated item of the `DiscriminantKind` trait.
     Discriminant,            sym::discriminant_type,   discriminant_type,          TypeAliasId,            GenericRequirement::None;
 
     PointeeTrait,            sym::pointee_trait,       pointee_trait,              TraitId,                GenericRequirement::None;
diff --git a/src/tools/rust-analyzer/crates/hir-def/src/nameres.rs b/src/tools/rust-analyzer/crates/hir-def/src/nameres.rs
@@ -739,7 +739,7 @@ impl ModuleData {
         self.origin.definition_source(db)
     }
 
-    /// Same as [`definition_source`] but only returns the file id to prevent parsing the ASt.
+    /// Same as [`ModuleData::definition_source`] but only returns the file id to prevent parsing the ASt.
     pub fn definition_source_file_id(&self) -> HirFileId {
         match self.origin {
             ModuleOrigin::File { definition, .. } | ModuleOrigin::CrateRoot { definition } => {
diff --git a/src/tools/rust-analyzer/crates/hir-expand/src/files.rs b/src/tools/rust-analyzer/crates/hir-expand/src/files.rs
@@ -295,7 +295,7 @@ impl<SN: Borrow<SyntaxNode>> InFile<SN> {
     /// Falls back to the macro call range if the node cannot be mapped up fully.
     ///
     /// For attributes and derives, this will point back to the attribute only.
-    /// For the entire item use [`InFile::original_file_range_full`].
+    /// For the entire item use `InFile::original_file_range_full`.
     pub fn original_file_range_rooted(self, db: &dyn db::ExpandDatabase) -> FileRange {
         self.borrow().map(SyntaxNode::text_range).original_node_file_range_rooted(db)
     }
diff --git a/src/tools/rust-analyzer/crates/hir-expand/src/hygiene.rs b/src/tools/rust-analyzer/crates/hir-expand/src/hygiene.rs
@@ -8,17 +8,17 @@
 //!
 //! # The Expansion Order Hierarchy
 //!
-//! `ExpnData` in rustc, rust-analyzer's version is [`MacroCallLoc`]. Traversing the hierarchy
-//! upwards can be achieved by walking up [`MacroCallLoc::kind`]'s contained file id, as
-//! [`MacroFile`]s are interned [`MacroCallLoc`]s.
+//! `ExpnData` in rustc, rust-analyzer's version is `MacroCallLoc`. Traversing the hierarchy
+//! upwards can be achieved by walking up `MacroCallLoc::kind`'s contained file id, as
+//! `MacroFile`s are interned `MacroCallLoc`s.
 //!
 //! # The Macro Definition Hierarchy
 //!
 //! `SyntaxContextData` in rustc and rust-analyzer. Basically the same in both.
 //!
 //! # The Call-site Hierarchy
 //!
-//! `ExpnData::call_site` in rustc, [`MacroCallLoc::call_site`] in rust-analyzer.
+//! `ExpnData::call_site` in rustc, `MacroCallLoc::call_site` in rust-analyzer.
 // FIXME: Move this into the span crate? Not quite possible today as that depends on `MacroCallLoc`
 // which contains a bunch of unrelated things
 
diff --git a/src/tools/rust-analyzer/crates/hir-expand/src/lib.rs b/src/tools/rust-analyzer/crates/hir-expand/src/lib.rs
@@ -4,6 +4,8 @@
 //! tree originates not from the text of some `FileId`, but from some macro
 //! expansion.
 #![cfg_attr(feature = "in-rust-tree", feature(rustc_private))]
+// It's useful to refer to code that is private in doc comments.
+#![allow(rustdoc::private_intra_doc_links)]
 
 pub use intern;
 
@@ -860,7 +862,7 @@ impl ExpansionInfo {
     }
 
     /// Maps the passed in file range down into a macro expansion if it is the input to a macro call.
-    /// Unlike [`map_range_down_exact`], this will consider spans that contain the given span.
+    /// Unlike [`ExpansionInfo::map_range_down_exact`], this will consider spans that contain the given span.
     ///
     /// Note this does a linear search through the entire backing vector of the spanmap.
     pub fn map_range_down(
diff --git a/src/tools/rust-analyzer/crates/hir-ty/src/lib.rs b/src/tools/rust-analyzer/crates/hir-ty/src/lib.rs
@@ -2,6 +2,8 @@
 //! information and various assists.
 
 #![cfg_attr(feature = "in-rust-tree", feature(rustc_private))]
+// It's useful to refer to code that is private in doc comments.
+#![allow(rustdoc::private_intra_doc_links)]
 
 // FIXME: We used to import `rustc_*` deps from `rustc_private` with `feature = "in-rust-tree" but
 // temporarily switched to crates.io versions due to hardships that working on them from rustc
diff --git a/src/tools/rust-analyzer/crates/hir-ty/src/mir.rs b/src/tools/rust-analyzer/crates/hir-ty/src/mir.rs
@@ -977,15 +977,13 @@ pub enum Rvalue<'db> {
     UnaryOp(UnOp, Operand<'db>),
 
     /// Computes the discriminant of the place, returning it as an integer of type
-    /// [`discriminant_ty`]. Returns zero for types without discriminant.
+    /// `discriminant_ty`. Returns zero for types without discriminant.
     ///
     /// The validity requirements for the underlying value are undecided for this rvalue, see
     /// [#91095]. Note too that the value of the discriminant is not the same thing as the
-    /// variant index; use [`discriminant_for_variant`] to convert.
+    /// variant index; use `discriminant_for_variant` to convert.
     ///
-    /// [`discriminant_ty`]: crate::ty::Ty::discriminant_ty
     /// [#91095]: https://github.com/rust-lang/rust/issues/91095
-    /// [`discriminant_for_variant`]: crate::ty::Ty::discriminant_for_variant
     Discriminant(Place<'db>),
 
     /// Creates an aggregate value, like a tuple or struct.
diff --git a/src/tools/rust-analyzer/crates/hir-ty/src/next_solver/infer/mod.rs b/src/tools/rust-analyzer/crates/hir-ty/src/next_solver/infer/mod.rs
@@ -402,7 +402,7 @@ impl<'db> InferCtxt<'db> {
         self.evaluate_obligation(obligation).may_apply()
     }
 
-    /// See the comment on [OpaqueTypesJank](crate::solve::OpaqueTypesJank)
+    /// See the comment on `GeneralAutoderef::overloaded_deref_ty`
     /// for more details.
     pub fn predicate_may_hold_opaque_types_jank(
         &self,
@@ -532,7 +532,7 @@ impl<'db> InferCtxt<'db> {
         })
     }
 
-    /// See the comment on [OpaqueTypesJank](crate::solve::OpaqueTypesJank)
+    /// See the comment on `GeneralAutoderef::overloaded_deref_ty`
     /// for more details.
     pub fn goal_may_hold_opaque_types_jank(&self, goal: Goal<'db, Predicate<'db>>) -> bool {
         <&SolverContext<'db>>::from(self).root_goal_may_hold_opaque_types_jank(goal)
diff --git a/src/tools/rust-analyzer/crates/hir/src/has_source.rs b/src/tools/rust-analyzer/crates/hir/src/has_source.rs
@@ -20,7 +20,7 @@ use crate::{
 pub trait HasSource {
     type Ast;
     /// Fetches the definition's source node.
-    /// Using [`crate::Semantics::source`] is preferred when working with [`crate::Semantics`],
+    /// Using [`crate::SemanticsImpl::source`] is preferred when working with [`crate::Semantics`],
     /// as that caches the parsed file in the semantics' cache.
     ///
     /// The current some implementations can return `InFile` instead of `Option<InFile>`.
diff --git a/src/tools/rust-analyzer/crates/ide-assists/src/lib.rs b/src/tools/rust-analyzer/crates/ide-assists/src/lib.rs
@@ -59,6 +59,8 @@
 //! <https://rust-analyzer.github.io/blog/2020/09/28/how-to-make-a-light-bulb.html>
 
 #![cfg_attr(feature = "in-rust-tree", feature(rustc_private))]
+// It's useful to refer to code that is private in doc comments.
+#![allow(rustdoc::private_intra_doc_links)]
 
 mod assist_config;
 mod assist_context;
diff --git a/src/tools/rust-analyzer/crates/ide-completion/src/item.rs b/src/tools/rust-analyzer/crates/ide-completion/src/item.rs
@@ -23,7 +23,7 @@ use crate::{
 /// editor pop-up.
 ///
 /// It is basically a POD with various properties. To construct a [`CompletionItem`],
-/// use [`Builder::new`] method and the [`Builder`] struct.
+/// use the [`Builder`] struct.
 #[derive(Clone, UpmapFromRaFixture)]
 #[non_exhaustive]
 pub struct CompletionItem {
diff --git a/src/tools/rust-analyzer/crates/ide-completion/src/lib.rs b/src/tools/rust-analyzer/crates/ide-completion/src/lib.rs
@@ -1,5 +1,8 @@
 //! `completions` crate provides utilities for generating completions of user input.
 
+// It's useful to refer to code that is private in doc comments.
+#![allow(rustdoc::private_intra_doc_links)]
+
 mod completions;
 mod config;
 mod context;
diff --git a/src/tools/rust-analyzer/crates/parser/src/lib.rs b/src/tools/rust-analyzer/crates/parser/src/lib.rs
@@ -3,9 +3,10 @@
 //! NOTE: The crate is undergoing refactors, don't believe everything the docs
 //! say :-)
 //!
-//! The parser doesn't know about concrete representation of tokens and syntax
-//! trees. Abstract [`TokenSource`] and [`TreeSink`] traits are used instead. As
-//! a consequence, this crate does not contain a lexer.
+//! The parser doesn't know about concrete representation of tokens
+//! and syntax trees. Abstract [`Input`] and [`Output`] traits are
+//! used to provide tokens instead. As a consequence, this crate does
+//! not contain a lexer.
 //!
 //! The [`Parser`] struct from the [`parser`] module is a cursor into the
 //! sequence of tokens.  Parsing routines use [`Parser`] to inspect current
diff --git a/src/tools/rust-analyzer/crates/paths/src/lib.rs b/src/tools/rust-analyzer/crates/paths/src/lib.rs
@@ -1,5 +1,5 @@
-//! Thin wrappers around [`camino::path`], distinguishing between absolute and
-//! relative paths.
+//! Thin wrappers around [`camino::Utf8PathBuf`], distinguishing
+//! between absolute and relative paths.
 
 use std::{
     borrow::Borrow,
diff --git a/src/tools/rust-analyzer/crates/proc-macro-api/src/legacy_protocol/msg.rs b/src/tools/rust-analyzer/crates/proc-macro-api/src/legacy_protocol/msg.rs
@@ -17,19 +17,19 @@ pub enum Request {
     // As such, this is the only request that needs to be supported across all protocol versions
     // and by keeping it first, we ensure it always has the same discriminant encoding in postcard
     /// Performs an API version check between the client and the server.
-    /// Since [`VERSION_CHECK_VERSION`]
+    /// Since [`crate::version::VERSION_CHECK_VERSION`]
     ApiVersionCheck {},
 
     /// Retrieves a list of macros from a given dynamic library.
-    /// Since [`NO_VERSION_CHECK_VERSION`]
+    /// Since [`crate::version::NO_VERSION_CHECK_VERSION`]
     ListMacros { dylib_path: Utf8PathBuf },
 
     /// Expands a procedural macro.
-    /// Since [`NO_VERSION_CHECK_VERSION`]
+    /// Since [`crate::version::NO_VERSION_CHECK_VERSION`]
     ExpandMacro(Box<ExpandMacro>),
 
     /// Sets server-specific configurations.
-    /// Since [`RUST_ANALYZER_SPAN_SUPPORT`]
+    /// Since [`crate::version::RUST_ANALYZER_SPAN_SUPPORT`]
     SetConfig(ServerConfig),
 }
 
@@ -51,23 +51,23 @@ pub enum Response {
     // As such, this is the only request that needs to be supported across all protocol versions
     // and by keeping it first, we ensure it always has the same discriminant encoding in postcard
     /// Returns the API version supported by the server.
-    /// Since [`NO_VERSION_CHECK_VERSION`]
+    /// Since [`crate::version::NO_VERSION_CHECK_VERSION`]
     ApiVersionCheck(u32),
 
     /// Returns a list of available macros in a dynamic library.
-    /// Since [`NO_VERSION_CHECK_VERSION`]
+    /// Since [`crate::version::NO_VERSION_CHECK_VERSION`]
     ListMacros(Result<Vec<(String, ProcMacroKind)>, String>),
 
     /// Returns result of a macro expansion.
-    /// Since [`NO_VERSION_CHECK_VERSION`]
+    /// Since [`crate::version::NO_VERSION_CHECK_VERSION`]
     ExpandMacro(Result<FlatTree, PanicMessage>),
 
     /// Confirms the application of a configuration update.
-    /// Since [`RUST_ANALYZER_SPAN_SUPPORT`]
+    /// Since [`crate::version::RUST_ANALYZER_SPAN_SUPPORT`]
     SetConfig(ServerConfig),
 
     /// Returns the result of a macro expansion, including extended span data.
-    /// Since [`RUST_ANALYZER_SPAN_SUPPORT`]
+    /// Since [`crate::version::RUST_ANALYZER_SPAN_SUPPORT`]
     ExpandMacroExtended(Result<ExpandMacroExtended, PanicMessage>),
 }
 
diff --git a/src/tools/rust-analyzer/crates/project-model/src/cargo_workspace.rs b/src/tools/rust-analyzer/crates/project-model/src/cargo_workspace.rs
@@ -305,7 +305,7 @@ impl TargetKind {
 
     /// If this is a valid cargo target, returns the name cargo uses in command line arguments
     /// and output, otherwise None.
-    /// https://docs.rs/cargo_metadata/latest/cargo_metadata/enum.TargetKind.html
+    /// <https://docs.rs/cargo_metadata/latest/cargo_metadata/enum.TargetKind.html>
     pub fn as_cargo_target(self) -> Option<&'static str> {
         match self {
             TargetKind::Bin => Some("bin"),
diff --git a/src/tools/rust-analyzer/crates/project-model/src/lib.rs b/src/tools/rust-analyzer/crates/project-model/src/lib.rs
@@ -1,7 +1,7 @@
 //! In rust-analyzer, we maintain a strict separation between pure abstract
 //! semantic project model and a concrete model of a particular build system.
 //!
-//! Pure model is represented by the [`base_db::CrateGraph`] from another crate.
+//! Pure model is represented by the `base_db::CrateGraph` from another crate.
 //!
 //! In this crate, we are concerned with "real world" project models.
 //!
@@ -13,7 +13,10 @@
 //! * Project discovery (where's the relevant Cargo.toml for the current dir).
 //! * Custom build steps (`build.rs` code generation and compilation of
 //!   procedural macros).
-//! * Lowering of concrete model to a [`base_db::CrateGraph`]
+//! * Lowering of concrete model to a `base_db::CrateGraph`
+
+// It's useful to refer to code that is private in doc comments.
+#![allow(rustdoc::private_intra_doc_links)]
 
 pub mod project_json;
 pub mod toolchain_info {
diff --git a/src/tools/rust-analyzer/crates/project-model/src/project_json.rs b/src/tools/rust-analyzer/crates/project-model/src/project_json.rs
@@ -1,6 +1,6 @@
 //! `rust-project.json` file format.
 //!
-//! This format is spiritually a serialization of [`base_db::CrateGraph`]. The
+//! This format is spiritually a serialization of `base_db::CrateGraph`. The
 //! idea here is that people who do not use Cargo, can instead teach their build
 //! system to generate `rust-project.json` which can be ingested by
 //! rust-analyzer.
diff --git a/src/tools/rust-analyzer/crates/project-model/src/workspace.rs b/src/tools/rust-analyzer/crates/project-model/src/workspace.rs
@@ -1044,7 +1044,7 @@ impl ProjectWorkspace {
 
     /// Returns `true` if the project workspace is [`Json`].
     ///
-    /// [`Json`]: ProjectWorkspace::Json
+    /// [`Json`]: ProjectWorkspaceKind::Json
     #[must_use]
     pub fn is_json(&self) -> bool {
         matches!(self.kind, ProjectWorkspaceKind::Json { .. })
diff --git a/src/tools/rust-analyzer/crates/span/src/ast_id.rs b/src/tools/rust-analyzer/crates/span/src/ast_id.rs
@@ -700,7 +700,7 @@ impl AstIdMap {
         }
     }
 
-    /// The [`AstId`] of the root node
+    /// The root node.
     pub fn root(&self) -> SyntaxNodePtr {
         self.arena[Idx::from_raw(RawIdx::from_u32(0))].0
     }
diff --git a/src/tools/rust-analyzer/crates/span/src/hygiene.rs b/src/tools/rust-analyzer/crates/span/src/hygiene.rs
@@ -249,7 +249,7 @@ const _: () = {
             )
         }
 
-        /// Invariant: Only [`SyntaxContext::ROOT`] has a [`None`] outer expansion.
+        /// Invariant: Only the root [`SyntaxContext`] has a [`None`] outer expansion.
         // FIXME: The None case needs to encode the context crate id. We can encode that as the MSB of
         // MacroCallId is reserved anyways so we can do bit tagging here just fine.
         // The bigger issue is that this will cause interning to now create completely separate chains
@@ -348,7 +348,7 @@ impl SyntaxContext {
         }
     }
 
-    /// The root context, which is the parent of all other contexts. All [`FileId`]s have this context.
+    /// The root context, which is the parent of all other contexts. All `FileId`s have this context.
     #[inline]
     pub const fn root(edition: Edition) -> Self {
         let edition = edition as u32;
diff --git a/src/tools/rust-analyzer/crates/test-utils/src/assert_linear.rs b/src/tools/rust-analyzer/crates/test-utils/src/assert_linear.rs
@@ -11,7 +11,7 @@
 //! Ideally, we should use a proper "model selection" to directly compare
 //! quadratic and linear models, but that sounds rather complicated:
 //!
-//! > https://stats.stackexchange.com/questions/21844/selecting-best-model-based-on-linear-quadratic-and-cubic-fit-of-data
+//! > <https://stats.stackexchange.com/questions/21844/selecting-best-model-based-on-linear-quadratic-and-cubic-fit-of-data>
 //!
 //! We might get false positives on a VM, but never false negatives. So, if the
 //! first round fails, we repeat the ordeal three more times and fail only if
diff --git a/src/tools/rust-analyzer/crates/test-utils/src/fixture.rs b/src/tools/rust-analyzer/crates/test-utils/src/fixture.rs
@@ -96,18 +96,19 @@ pub struct Fixture {
     ///
     /// Syntax: `cfg:test,dbg=false,opt_level=2`
     pub cfgs: Vec<(String, Option<String>)>,
-    /// Specifies the edition of this crate. This must be used with `crate` meta. If
-    /// this is not specified, ([`base_db::input::Edition::CURRENT`]) will be used.
-    /// This must be used with `crate` meta.
+    /// Specifies the edition of this crate. This must be used with
+    /// `crate` meta. If this is not specified,
+    /// `base_db::input::Edition::CURRENT` will be used.  This must be
+    /// used with `crate` meta.
     ///
     /// Syntax: `edition:2021`
     pub edition: Option<String>,
     /// Specifies environment variables.
     ///
     /// Syntax: `env:PATH=/bin,RUST_LOG=debug`
     pub env: FxHashMap<String, String>,
-    /// Introduces a new [source root](base_db::input::SourceRoot). This file **and
-    /// the following files** will belong the new source root. This must be used
+    /// Introduces a new source root. This file **and the following
+    /// files** will belong the new source root. This must be used
     /// with `crate` meta.
     ///
     /// Use this if you want to test something that uses `SourceRoot::is_library()`
@@ -126,7 +127,7 @@ pub struct Fixture {
     /// This is implied if this file belongs to a library source root.
     ///
     /// Use this if you want to test something that checks if a crate is a workspace
-    /// member via [`CrateOrigin`](base_db::input::CrateOrigin).
+    /// member via `CrateOrigin`.
     ///
     /// Syntax: `library`
     pub library: bool,

Original file line number	Diff line number	Diff line change
`@@ -739,7 +739,7 @@ impl ModuleData {`
`739`	`739`	`self.origin.definition_source(db)`
`740`	`740`	`}`
`741`	`741`
`742`		- /// Same as [`definition_source`] but only returns the file id to prevent parsing the ASt.
	`742`	+ /// Same as [`ModuleData::definition_source`] but only returns the file id to prevent parsing the ASt.
`743`	`743`	`pub fn definition_source_file_id(&self) -> HirFileId {`
`744`	`744`	`match self.origin {`
`745`	`745`	`ModuleOrigin::File { definition, .. } \| ModuleOrigin::CrateRoot { definition } => {`
Original file line number	Diff line number	Diff line change
`@@ -295,7 +295,7 @@ impl<SN: Borrow<SyntaxNode>> InFile<SN> {`
`295`	`295`	`/// Falls back to the macro call range if the node cannot be mapped up fully.`
`296`	`296`	`///`
`297`	`297`	`/// For attributes and derives, this will point back to the attribute only.`
`298`		- /// For the entire item use [`InFile::original_file_range_full`].
	`298`	+ /// For the entire item use `InFile::original_file_range_full`.
`299`	`299`	`pub fn original_file_range_rooted(self, db: &dyn db::ExpandDatabase) -> FileRange {`
`300`	`300`	`self.borrow().map(SyntaxNode::text_range).original_node_file_range_rooted(db)`
`301`	`301`	`}`