rustdoc/passes/
collect_intra_doc_links.rs

1//! This module implements [RFC 1946]: Intra-rustdoc-links
2//!
3//! [RFC 1946]: https://github.com/rust-lang/rfcs/blob/master/text/1946-intra-rustdoc-links.md
4
5use std::borrow::Cow;
6use std::fmt::Display;
7use std::mem;
8use std::ops::Range;
9
10use pulldown_cmark::LinkType;
11use rustc_ast::util::comments::may_have_doc_links;
12use rustc_data_structures::fx::{FxHashMap, FxHashSet, FxIndexMap, FxIndexSet};
13use rustc_data_structures::intern::Interned;
14use rustc_errors::{Applicability, Diag, DiagMessage};
15use rustc_hir::def::Namespace::*;
16use rustc_hir::def::{DefKind, Namespace, PerNS};
17use rustc_hir::def_id::{CRATE_DEF_ID, DefId, LOCAL_CRATE};
18use rustc_hir::{Mutability, Safety};
19use rustc_middle::ty::{Ty, TyCtxt};
20use rustc_middle::{bug, span_bug, ty};
21use rustc_resolve::rustdoc::{
22    MalformedGenerics, has_primitive_or_keyword_docs, prepare_to_doc_link_resolution,
23    source_span_for_markdown_range, strip_generics_from_path,
24};
25use rustc_session::lint::Lint;
26use rustc_span::BytePos;
27use rustc_span::hygiene::MacroKind;
28use rustc_span::symbol::{Ident, Symbol, sym};
29use smallvec::{SmallVec, smallvec};
30use tracing::{debug, info, instrument, trace};
31
32use crate::clean::utils::find_nearest_parent_module;
33use crate::clean::{self, Crate, Item, ItemId, ItemLink, PrimitiveType};
34use crate::core::DocContext;
35use crate::html::markdown::{MarkdownLink, MarkdownLinkRange, markdown_links};
36use crate::lint::{BROKEN_INTRA_DOC_LINKS, PRIVATE_INTRA_DOC_LINKS};
37use crate::passes::Pass;
38use crate::visit::DocVisitor;
39
40pub(crate) const COLLECT_INTRA_DOC_LINKS: Pass =
41    Pass { name: "collect-intra-doc-links", run: None, description: "resolves intra-doc links" };
42
43pub(crate) fn collect_intra_doc_links<'a, 'tcx>(
44    krate: Crate,
45    cx: &'a mut DocContext<'tcx>,
46) -> (Crate, LinkCollector<'a, 'tcx>) {
47    let mut collector = LinkCollector {
48        cx,
49        visited_links: FxHashMap::default(),
50        ambiguous_links: FxIndexMap::default(),
51    };
52    collector.visit_crate(&krate);
53    (krate, collector)
54}
55
56fn filter_assoc_items_by_name_and_namespace(
57    tcx: TyCtxt<'_>,
58    assoc_items_of: DefId,
59    ident: Ident,
60    ns: Namespace,
61) -> impl Iterator<Item = &ty::AssocItem> {
62    let iter: Box<dyn Iterator<Item = &ty::AssocItem>> = if !ident.name.is_empty() {
63        Box::new(tcx.associated_items(assoc_items_of).filter_by_name_unhygienic(ident.name))
64    } else {
65        Box::new([].iter())
66    };
67    iter.filter(move |item| {
68        item.namespace() == ns && tcx.hygienic_eq(ident, item.ident(tcx), assoc_items_of)
69    })
70}
71
72#[derive(Copy, Clone, Debug, Hash, PartialEq)]
73pub(crate) enum Res {
74    Def(DefKind, DefId),
75    Primitive(PrimitiveType),
76}
77
78type ResolveRes = rustc_hir::def::Res<rustc_ast::NodeId>;
79
80impl Res {
81    fn descr(self) -> &'static str {
82        match self {
83            Res::Def(kind, id) => ResolveRes::Def(kind, id).descr(),
84            Res::Primitive(_) => "primitive type",
85        }
86    }
87
88    fn article(self) -> &'static str {
89        match self {
90            Res::Def(kind, id) => ResolveRes::Def(kind, id).article(),
91            Res::Primitive(_) => "a",
92        }
93    }
94
95    fn name(self, tcx: TyCtxt<'_>) -> Symbol {
96        match self {
97            Res::Def(_, id) => tcx.item_name(id),
98            Res::Primitive(prim) => prim.as_sym(),
99        }
100    }
101
102    fn def_id(self, tcx: TyCtxt<'_>) -> Option<DefId> {
103        match self {
104            Res::Def(_, id) => Some(id),
105            Res::Primitive(prim) => PrimitiveType::primitive_locations(tcx).get(&prim).copied(),
106        }
107    }
108
109    fn from_def_id(tcx: TyCtxt<'_>, def_id: DefId) -> Res {
110        Res::Def(tcx.def_kind(def_id), def_id)
111    }
112
113    /// Used for error reporting.
114    fn disambiguator_suggestion(self) -> Suggestion {
115        let kind = match self {
116            Res::Primitive(_) => return Suggestion::Prefix("prim"),
117            Res::Def(kind, _) => kind,
118        };
119
120        let prefix = match kind {
121            DefKind::Fn | DefKind::AssocFn => return Suggestion::Function,
122            DefKind::Macro(MacroKind::Bang) => return Suggestion::Macro,
123
124            DefKind::Macro(MacroKind::Derive) => "derive",
125            DefKind::Struct => "struct",
126            DefKind::Enum => "enum",
127            DefKind::Trait => "trait",
128            DefKind::Union => "union",
129            DefKind::Mod => "mod",
130            DefKind::Const | DefKind::ConstParam | DefKind::AssocConst | DefKind::AnonConst => {
131                "const"
132            }
133            DefKind::Static { .. } => "static",
134            DefKind::Field => "field",
135            DefKind::Variant | DefKind::Ctor(..) => "variant",
136            // Now handle things that don't have a specific disambiguator
137            _ => match kind
138                .ns()
139                .expect("tried to calculate a disambiguator for a def without a namespace?")
140            {
141                Namespace::TypeNS => "type",
142                Namespace::ValueNS => "value",
143                Namespace::MacroNS => "macro",
144            },
145        };
146
147        Suggestion::Prefix(prefix)
148    }
149}
150
151impl TryFrom<ResolveRes> for Res {
152    type Error = ();
153
154    fn try_from(res: ResolveRes) -> Result<Self, ()> {
155        use rustc_hir::def::Res::*;
156        match res {
157            Def(kind, id) => Ok(Res::Def(kind, id)),
158            PrimTy(prim) => Ok(Res::Primitive(PrimitiveType::from_hir(prim))),
159            // e.g. `#[derive]`
160            ToolMod | NonMacroAttr(..) | Err => Result::Err(()),
161            other => bug!("unrecognized res {other:?}"),
162        }
163    }
164}
165
166/// The link failed to resolve. [`resolution_failure`] should look to see if there's
167/// a more helpful error that can be given.
168#[derive(Debug)]
169struct UnresolvedPath<'a> {
170    /// Item on which the link is resolved, used for resolving `Self`.
171    item_id: DefId,
172    /// The scope the link was resolved in.
173    module_id: DefId,
174    /// If part of the link resolved, this has the `Res`.
175    ///
176    /// In `[std::io::Error::x]`, `std::io::Error` would be a partial resolution.
177    partial_res: Option<Res>,
178    /// The remaining unresolved path segments.
179    ///
180    /// In `[std::io::Error::x]`, `x` would be unresolved.
181    unresolved: Cow<'a, str>,
182}
183
184#[derive(Debug)]
185enum ResolutionFailure<'a> {
186    /// This resolved, but with the wrong namespace.
187    WrongNamespace {
188        /// What the link resolved to.
189        res: Res,
190        /// The expected namespace for the resolution, determined from the link's disambiguator.
191        ///
192        /// E.g., for `[fn@Result]` this is [`Namespace::ValueNS`],
193        /// even though `Result`'s actual namespace is [`Namespace::TypeNS`].
194        expected_ns: Namespace,
195    },
196    NotResolved(UnresolvedPath<'a>),
197}
198
199#[derive(Clone, Debug, Hash, PartialEq, Eq)]
200pub(crate) enum UrlFragment {
201    Item(DefId),
202    /// A part of a page that isn't a rust item.
203    ///
204    /// Eg: `[Vector Examples](std::vec::Vec#examples)`
205    UserWritten(String),
206}
207
208impl UrlFragment {
209    /// Render the fragment, including the leading `#`.
210    pub(crate) fn render(&self, s: &mut String, tcx: TyCtxt<'_>) {
211        s.push('#');
212        match self {
213            &UrlFragment::Item(def_id) => {
214                let kind = match tcx.def_kind(def_id) {
215                    DefKind::AssocFn => {
216                        if tcx.defaultness(def_id).has_value() {
217                            "method."
218                        } else {
219                            "tymethod."
220                        }
221                    }
222                    DefKind::AssocConst => "associatedconstant.",
223                    DefKind::AssocTy => "associatedtype.",
224                    DefKind::Variant => "variant.",
225                    DefKind::Field => {
226                        let parent_id = tcx.parent(def_id);
227                        if tcx.def_kind(parent_id) == DefKind::Variant {
228                            s.push_str("variant.");
229                            s.push_str(tcx.item_name(parent_id).as_str());
230                            ".field."
231                        } else {
232                            "structfield."
233                        }
234                    }
235                    kind => bug!("unexpected associated item kind: {kind:?}"),
236                };
237                s.push_str(kind);
238                s.push_str(tcx.item_name(def_id).as_str());
239            }
240            UrlFragment::UserWritten(raw) => s.push_str(raw),
241        }
242    }
243}
244
245#[derive(Clone, Debug, Hash, PartialEq, Eq)]
246pub(crate) struct ResolutionInfo {
247    item_id: DefId,
248    module_id: DefId,
249    dis: Option<Disambiguator>,
250    path_str: Box<str>,
251    extra_fragment: Option<String>,
252}
253
254#[derive(Clone)]
255pub(crate) struct DiagnosticInfo<'a> {
256    item: &'a Item,
257    dox: &'a str,
258    ori_link: &'a str,
259    link_range: MarkdownLinkRange,
260}
261
262pub(crate) struct OwnedDiagnosticInfo {
263    item: Item,
264    dox: String,
265    ori_link: String,
266    link_range: MarkdownLinkRange,
267}
268
269impl From<DiagnosticInfo<'_>> for OwnedDiagnosticInfo {
270    fn from(f: DiagnosticInfo<'_>) -> Self {
271        Self {
272            item: f.item.clone(),
273            dox: f.dox.to_string(),
274            ori_link: f.ori_link.to_string(),
275            link_range: f.link_range.clone(),
276        }
277    }
278}
279
280impl OwnedDiagnosticInfo {
281    pub(crate) fn into_info(&self) -> DiagnosticInfo<'_> {
282        DiagnosticInfo {
283            item: &self.item,
284            ori_link: &self.ori_link,
285            dox: &self.dox,
286            link_range: self.link_range.clone(),
287        }
288    }
289}
290
291pub(crate) struct LinkCollector<'a, 'tcx> {
292    pub(crate) cx: &'a mut DocContext<'tcx>,
293    /// Cache the resolved links so we can avoid resolving (and emitting errors for) the same link.
294    /// The link will be `None` if it could not be resolved (i.e. the error was cached).
295    pub(crate) visited_links: FxHashMap<ResolutionInfo, Option<(Res, Option<UrlFragment>)>>,
296    /// According to `rustc_resolve`, these links are ambiguous.
297    ///
298    /// However, we cannot link to an item that has been stripped from the documentation. If all
299    /// but one of the "possibilities" are stripped, then there is no real ambiguity. To determine
300    /// if an ambiguity is real, we delay resolving them until after `Cache::populate`, then filter
301    /// every item that doesn't have a cached path.
302    ///
303    /// We could get correct results by simply delaying everything. This would have fewer happy
304    /// codepaths, but we want to distinguish different kinds of error conditions, and this is easy
305    /// to do by resolving links as soon as possible.
306    pub(crate) ambiguous_links: FxIndexMap<(ItemId, String), Vec<AmbiguousLinks>>,
307}
308
309pub(crate) struct AmbiguousLinks {
310    link_text: Box<str>,
311    diag_info: OwnedDiagnosticInfo,
312    resolved: Vec<(Res, Option<UrlFragment>)>,
313}
314
315impl<'tcx> LinkCollector<'_, 'tcx> {
316    /// Given a full link, parse it as an [enum struct variant].
317    ///
318    /// In particular, this will return an error whenever there aren't three
319    /// full path segments left in the link.
320    ///
321    /// [enum struct variant]: rustc_hir::VariantData::Struct
322    fn variant_field<'path>(
323        &self,
324        path_str: &'path str,
325        item_id: DefId,
326        module_id: DefId,
327    ) -> Result<(Res, DefId), UnresolvedPath<'path>> {
328        let tcx = self.cx.tcx;
329        let no_res = || UnresolvedPath {
330            item_id,
331            module_id,
332            partial_res: None,
333            unresolved: path_str.into(),
334        };
335
336        debug!("looking for enum variant {path_str}");
337        let mut split = path_str.rsplitn(3, "::");
338        let variant_field_name = Symbol::intern(split.next().unwrap());
339        // We're not sure this is a variant at all, so use the full string.
340        // If there's no second component, the link looks like `[path]`.
341        // So there's no partial res and we should say the whole link failed to resolve.
342        let variant_name = Symbol::intern(split.next().ok_or_else(no_res)?);
343
344        // If there's no third component, we saw `[a::b]` before and it failed to resolve.
345        // So there's no partial res.
346        let path = split.next().ok_or_else(no_res)?;
347        let ty_res = self.resolve_path(path, TypeNS, item_id, module_id).ok_or_else(no_res)?;
348
349        match ty_res {
350            Res::Def(DefKind::Enum, did) => match tcx.type_of(did).instantiate_identity().kind() {
351                ty::Adt(def, _) if def.is_enum() => {
352                    if let Some(variant) = def.variants().iter().find(|v| v.name == variant_name)
353                        && let Some(field) =
354                            variant.fields.iter().find(|f| f.name == variant_field_name)
355                    {
356                        Ok((ty_res, field.did))
357                    } else {
358                        Err(UnresolvedPath {
359                            item_id,
360                            module_id,
361                            partial_res: Some(Res::Def(DefKind::Enum, def.did())),
362                            unresolved: variant_field_name.to_string().into(),
363                        })
364                    }
365                }
366                _ => unreachable!(),
367            },
368            _ => Err(UnresolvedPath {
369                item_id,
370                module_id,
371                partial_res: Some(ty_res),
372                unresolved: variant_name.to_string().into(),
373            }),
374        }
375    }
376
377    /// Given a primitive type, try to resolve an associated item.
378    fn resolve_primitive_associated_item(
379        &self,
380        prim_ty: PrimitiveType,
381        ns: Namespace,
382        item_name: Symbol,
383    ) -> Vec<(Res, DefId)> {
384        let tcx = self.cx.tcx;
385
386        prim_ty
387            .impls(tcx)
388            .flat_map(|impl_| {
389                filter_assoc_items_by_name_and_namespace(
390                    tcx,
391                    impl_,
392                    Ident::with_dummy_span(item_name),
393                    ns,
394                )
395                .map(|item| (Res::Primitive(prim_ty), item.def_id))
396            })
397            .collect::<Vec<_>>()
398    }
399
400    fn resolve_self_ty(&self, path_str: &str, ns: Namespace, item_id: DefId) -> Option<Res> {
401        if ns != TypeNS || path_str != "Self" {
402            return None;
403        }
404
405        let tcx = self.cx.tcx;
406        let self_id = match tcx.def_kind(item_id) {
407            def_kind @ (DefKind::AssocFn
408            | DefKind::AssocConst
409            | DefKind::AssocTy
410            | DefKind::Variant
411            | DefKind::Field) => {
412                let parent_def_id = tcx.parent(item_id);
413                if def_kind == DefKind::Field && tcx.def_kind(parent_def_id) == DefKind::Variant {
414                    tcx.parent(parent_def_id)
415                } else {
416                    parent_def_id
417                }
418            }
419            _ => item_id,
420        };
421
422        match tcx.def_kind(self_id) {
423            DefKind::Impl { .. } => self.def_id_to_res(self_id),
424            DefKind::Use => None,
425            def_kind => Some(Res::Def(def_kind, self_id)),
426        }
427    }
428
429    /// Convenience wrapper around `doc_link_resolutions`.
430    ///
431    /// This also handles resolving `true` and `false` as booleans.
432    /// NOTE: `doc_link_resolutions` knows only about paths, not about types.
433    /// Associated items will never be resolved by this function.
434    fn resolve_path(
435        &self,
436        path_str: &str,
437        ns: Namespace,
438        item_id: DefId,
439        module_id: DefId,
440    ) -> Option<Res> {
441        if let res @ Some(..) = self.resolve_self_ty(path_str, ns, item_id) {
442            return res;
443        }
444
445        // Resolver doesn't know about true, false, and types that aren't paths (e.g. `()`).
446        let result = self
447            .cx
448            .tcx
449            .doc_link_resolutions(module_id)
450            .get(&(Symbol::intern(path_str), ns))
451            .copied()
452            // NOTE: do not remove this panic! Missing links should be recorded as `Res::Err`; if
453            // `doc_link_resolutions` is missing a `path_str`, that means that there are valid links
454            // that are being missed. To fix the ICE, change
455            // `rustc_resolve::rustdoc::attrs_to_preprocessed_links` to cache the link.
456            .unwrap_or_else(|| {
457                span_bug!(
458                    self.cx.tcx.def_span(item_id),
459                    "no resolution for {path_str:?} {ns:?} {module_id:?}",
460                )
461            })
462            .and_then(|res| res.try_into().ok())
463            .or_else(|| resolve_primitive(path_str, ns));
464        debug!("{path_str} resolved to {result:?} in namespace {ns:?}");
465        result
466    }
467
468    /// Resolves a string as a path within a particular namespace. Returns an
469    /// optional URL fragment in the case of variants and methods.
470    fn resolve<'path>(
471        &mut self,
472        path_str: &'path str,
473        ns: Namespace,
474        disambiguator: Option<Disambiguator>,
475        item_id: DefId,
476        module_id: DefId,
477    ) -> Result<Vec<(Res, Option<DefId>)>, UnresolvedPath<'path>> {
478        if let Some(res) = self.resolve_path(path_str, ns, item_id, module_id) {
479            return Ok(match res {
480                Res::Def(
481                    DefKind::AssocFn | DefKind::AssocConst | DefKind::AssocTy | DefKind::Variant,
482                    def_id,
483                ) => {
484                    vec![(Res::from_def_id(self.cx.tcx, self.cx.tcx.parent(def_id)), Some(def_id))]
485                }
486                _ => vec![(res, None)],
487            });
488        } else if ns == MacroNS {
489            return Err(UnresolvedPath {
490                item_id,
491                module_id,
492                partial_res: None,
493                unresolved: path_str.into(),
494            });
495        }
496
497        // Try looking for methods and associated items.
498        // NB: `path_root` could be empty when resolving in the root namespace (e.g. `::std`).
499        let (path_root, item_str) = match path_str.rsplit_once("::") {
500            Some(res @ (_path_root, item_str)) if !item_str.is_empty() => res,
501            _ => {
502                // If there's no `::`, or the `::` is at the end (e.g. `String::`) it's not an
503                // associated item. So we can be sure that `rustc_resolve` was accurate when it
504                // said it wasn't resolved.
505                debug!("`::` missing or at end, assuming {path_str} was not in scope");
506                return Err(UnresolvedPath {
507                    item_id,
508                    module_id,
509                    partial_res: None,
510                    unresolved: path_str.into(),
511                });
512            }
513        };
514        let item_name = Symbol::intern(item_str);
515
516        // FIXME(#83862): this arbitrarily gives precedence to primitives over modules to support
517        // links to primitives when `#[rustc_doc_primitive]` is present. It should give an ambiguity
518        // error instead and special case *only* modules with `#[rustc_doc_primitive]`, not all
519        // primitives.
520        match resolve_primitive(path_root, TypeNS)
521            .or_else(|| self.resolve_path(path_root, TypeNS, item_id, module_id))
522            .map(|ty_res| {
523                self.resolve_associated_item(ty_res, item_name, ns, disambiguator, module_id)
524                    .into_iter()
525                    .map(|(res, def_id)| (res, Some(def_id)))
526                    .collect::<Vec<_>>()
527            }) {
528            Some(r) if !r.is_empty() => Ok(r),
529            _ => {
530                if ns == Namespace::ValueNS {
531                    self.variant_field(path_str, item_id, module_id)
532                        .map(|(res, def_id)| vec![(res, Some(def_id))])
533                } else {
534                    Err(UnresolvedPath {
535                        item_id,
536                        module_id,
537                        partial_res: None,
538                        unresolved: path_root.into(),
539                    })
540                }
541            }
542        }
543    }
544
545    /// Convert a DefId to a Res, where possible.
546    ///
547    /// This is used for resolving type aliases.
548    fn def_id_to_res(&self, ty_id: DefId) -> Option<Res> {
549        use PrimitiveType::*;
550        Some(match *self.cx.tcx.type_of(ty_id).instantiate_identity().kind() {
551            ty::Bool => Res::Primitive(Bool),
552            ty::Char => Res::Primitive(Char),
553            ty::Int(ity) => Res::Primitive(ity.into()),
554            ty::Uint(uty) => Res::Primitive(uty.into()),
555            ty::Float(fty) => Res::Primitive(fty.into()),
556            ty::Str => Res::Primitive(Str),
557            ty::Tuple(tys) if tys.is_empty() => Res::Primitive(Unit),
558            ty::Tuple(_) => Res::Primitive(Tuple),
559            ty::Pat(..) => Res::Primitive(Pat),
560            ty::Array(..) => Res::Primitive(Array),
561            ty::Slice(_) => Res::Primitive(Slice),
562            ty::RawPtr(_, _) => Res::Primitive(RawPointer),
563            ty::Ref(..) => Res::Primitive(Reference),
564            ty::FnDef(..) => panic!("type alias to a function definition"),
565            ty::FnPtr(..) => Res::Primitive(Fn),
566            ty::Never => Res::Primitive(Never),
567            ty::Adt(ty::AdtDef(Interned(&ty::AdtDefData { did, .. }, _)), _) | ty::Foreign(did) => {
568                Res::from_def_id(self.cx.tcx, did)
569            }
570            ty::Alias(..)
571            | ty::Closure(..)
572            | ty::CoroutineClosure(..)
573            | ty::Coroutine(..)
574            | ty::CoroutineWitness(..)
575            | ty::Dynamic(..)
576            | ty::UnsafeBinder(_)
577            | ty::Param(_)
578            | ty::Bound(..)
579            | ty::Placeholder(_)
580            | ty::Infer(_)
581            | ty::Error(_) => return None,
582        })
583    }
584
585    /// Convert a PrimitiveType to a Ty, where possible.
586    ///
587    /// This is used for resolving trait impls for primitives
588    fn primitive_type_to_ty(&mut self, prim: PrimitiveType) -> Option<Ty<'tcx>> {
589        use PrimitiveType::*;
590        let tcx = self.cx.tcx;
591
592        // FIXME: Only simple types are supported here, see if we can support
593        // other types such as Tuple, Array, Slice, etc.
594        // See https://github.com/rust-lang/rust/issues/90703#issuecomment-1004263455
595        Some(match prim {
596            Bool => tcx.types.bool,
597            Str => tcx.types.str_,
598            Char => tcx.types.char,
599            Never => tcx.types.never,
600            I8 => tcx.types.i8,
601            I16 => tcx.types.i16,
602            I32 => tcx.types.i32,
603            I64 => tcx.types.i64,
604            I128 => tcx.types.i128,
605            Isize => tcx.types.isize,
606            F16 => tcx.types.f16,
607            F32 => tcx.types.f32,
608            F64 => tcx.types.f64,
609            F128 => tcx.types.f128,
610            U8 => tcx.types.u8,
611            U16 => tcx.types.u16,
612            U32 => tcx.types.u32,
613            U64 => tcx.types.u64,
614            U128 => tcx.types.u128,
615            Usize => tcx.types.usize,
616            _ => return None,
617        })
618    }
619
620    /// Resolve an associated item, returning its containing page's `Res`
621    /// and the fragment targeting the associated item on its page.
622    fn resolve_associated_item(
623        &mut self,
624        root_res: Res,
625        item_name: Symbol,
626        ns: Namespace,
627        disambiguator: Option<Disambiguator>,
628        module_id: DefId,
629    ) -> Vec<(Res, DefId)> {
630        let tcx = self.cx.tcx;
631
632        match root_res {
633            Res::Primitive(prim) => {
634                let items = self.resolve_primitive_associated_item(prim, ns, item_name);
635                if !items.is_empty() {
636                    items
637                // Inherent associated items take precedence over items that come from trait impls.
638                } else {
639                    self.primitive_type_to_ty(prim)
640                        .map(|ty| {
641                            resolve_associated_trait_item(ty, module_id, item_name, ns, self.cx)
642                                .iter()
643                                .map(|item| (root_res, item.def_id))
644                                .collect::<Vec<_>>()
645                        })
646                        .unwrap_or_default()
647                }
648            }
649            Res::Def(DefKind::TyAlias, did) => {
650                // Resolve the link on the type the alias points to.
651                // FIXME: if the associated item is defined directly on the type alias,
652                // it will show up on its documentation page, we should link there instead.
653                let Some(res) = self.def_id_to_res(did) else { return Vec::new() };
654                self.resolve_associated_item(res, item_name, ns, disambiguator, module_id)
655            }
656            Res::Def(
657                def_kind @ (DefKind::Struct | DefKind::Union | DefKind::Enum | DefKind::ForeignTy),
658                did,
659            ) => {
660                debug!("looking for associated item named {item_name} for item {did:?}");
661                // Checks if item_name is a variant of the `SomeItem` enum
662                if ns == TypeNS && def_kind == DefKind::Enum {
663                    match tcx.type_of(did).instantiate_identity().kind() {
664                        ty::Adt(adt_def, _) => {
665                            for variant in adt_def.variants() {
666                                if variant.name == item_name {
667                                    return vec![(root_res, variant.def_id)];
668                                }
669                            }
670                        }
671                        _ => unreachable!(),
672                    }
673                }
674
675                let search_for_field = || {
676                    let (DefKind::Struct | DefKind::Union) = def_kind else { return vec![] };
677                    debug!("looking for fields named {item_name} for {did:?}");
678                    // FIXME: this doesn't really belong in `associated_item` (maybe `variant_field` is better?)
679                    // NOTE: it's different from variant_field because it only resolves struct fields,
680                    // not variant fields (2 path segments, not 3).
681                    //
682                    // We need to handle struct (and union) fields in this code because
683                    // syntactically their paths are identical to associated item paths:
684                    // `module::Type::field` and `module::Type::Assoc`.
685                    //
686                    // On the other hand, variant fields can't be mistaken for associated
687                    // items because they look like this: `module::Type::Variant::field`.
688                    //
689                    // Variants themselves don't need to be handled here, even though
690                    // they also look like associated items (`module::Type::Variant`),
691                    // because they are real Rust syntax (unlike the intra-doc links
692                    // field syntax) and are handled by the compiler's resolver.
693                    let ty::Adt(def, _) = tcx.type_of(did).instantiate_identity().kind() else {
694                        unreachable!()
695                    };
696                    def.non_enum_variant()
697                        .fields
698                        .iter()
699                        .filter(|field| field.name == item_name)
700                        .map(|field| (root_res, field.did))
701                        .collect::<Vec<_>>()
702                };
703
704                if let Some(Disambiguator::Kind(DefKind::Field)) = disambiguator {
705                    return search_for_field();
706                }
707
708                // Checks if item_name belongs to `impl SomeItem`
709                let mut assoc_items: Vec<_> = tcx
710                    .inherent_impls(did)
711                    .iter()
712                    .flat_map(|&imp| {
713                        filter_assoc_items_by_name_and_namespace(
714                            tcx,
715                            imp,
716                            Ident::with_dummy_span(item_name),
717                            ns,
718                        )
719                    })
720                    .map(|item| (root_res, item.def_id))
721                    .collect();
722
723                if assoc_items.is_empty() {
724                    // Check if item_name belongs to `impl SomeTrait for SomeItem`
725                    // FIXME(#74563): This gives precedence to `impl SomeItem`:
726                    // Although having both would be ambiguous, use impl version for compatibility's sake.
727                    // To handle that properly resolve() would have to support
728                    // something like [`ambi_fn`](<SomeStruct as SomeTrait>::ambi_fn)
729                    assoc_items = resolve_associated_trait_item(
730                        tcx.type_of(did).instantiate_identity(),
731                        module_id,
732                        item_name,
733                        ns,
734                        self.cx,
735                    )
736                    .into_iter()
737                    .map(|item| (root_res, item.def_id))
738                    .collect::<Vec<_>>();
739                }
740
741                debug!("got associated item {assoc_items:?}");
742
743                if !assoc_items.is_empty() {
744                    return assoc_items;
745                }
746
747                if ns != Namespace::ValueNS {
748                    return Vec::new();
749                }
750
751                search_for_field()
752            }
753            Res::Def(DefKind::Trait, did) => filter_assoc_items_by_name_and_namespace(
754                tcx,
755                did,
756                Ident::with_dummy_span(item_name),
757                ns,
758            )
759            .map(|item| {
760                let res = Res::Def(item.as_def_kind(), item.def_id);
761                (res, item.def_id)
762            })
763            .collect::<Vec<_>>(),
764            _ => Vec::new(),
765        }
766    }
767}
768
769fn full_res(tcx: TyCtxt<'_>, (base, assoc_item): (Res, Option<DefId>)) -> Res {
770    assoc_item.map_or(base, |def_id| Res::from_def_id(tcx, def_id))
771}
772
773/// Look to see if a resolved item has an associated item named `item_name`.
774///
775/// Given `[std::io::Error::source]`, where `source` is unresolved, this would
776/// find `std::error::Error::source` and return
777/// `<io::Error as error::Error>::source`.
778fn resolve_associated_trait_item<'a>(
779    ty: Ty<'a>,
780    module: DefId,
781    item_name: Symbol,
782    ns: Namespace,
783    cx: &mut DocContext<'a>,
784) -> Vec<ty::AssocItem> {
785    // FIXME: this should also consider blanket impls (`impl<T> X for T`). Unfortunately
786    // `get_auto_trait_and_blanket_impls` is broken because the caching behavior is wrong. In the
787    // meantime, just don't look for these blanket impls.
788
789    // Next consider explicit impls: `impl MyTrait for MyType`
790    // Give precedence to inherent impls.
791    let traits = trait_impls_for(cx, ty, module);
792    let tcx = cx.tcx;
793    debug!("considering traits {traits:?}");
794    let candidates = traits
795        .iter()
796        .flat_map(|&(impl_, trait_)| {
797            filter_assoc_items_by_name_and_namespace(
798                tcx,
799                trait_,
800                Ident::with_dummy_span(item_name),
801                ns,
802            )
803            .map(move |trait_assoc| {
804                trait_assoc_to_impl_assoc_item(tcx, impl_, trait_assoc.def_id)
805                    .unwrap_or(*trait_assoc)
806            })
807        })
808        .collect::<Vec<_>>();
809    // FIXME(#74563): warn about ambiguity
810    debug!("the candidates were {candidates:?}");
811    candidates
812}
813
814/// Find the associated item in the impl `impl_id` that corresponds to the
815/// trait associated item `trait_assoc_id`.
816///
817/// This function returns `None` if no associated item was found in the impl.
818/// This can occur when the trait associated item has a default value that is
819/// not overridden in the impl.
820///
821/// This is just a wrapper around [`TyCtxt::impl_item_implementor_ids()`] and
822/// [`TyCtxt::associated_item()`] (with some helpful logging added).
823#[instrument(level = "debug", skip(tcx), ret)]
824fn trait_assoc_to_impl_assoc_item<'tcx>(
825    tcx: TyCtxt<'tcx>,
826    impl_id: DefId,
827    trait_assoc_id: DefId,
828) -> Option<ty::AssocItem> {
829    let trait_to_impl_assoc_map = tcx.impl_item_implementor_ids(impl_id);
830    debug!(?trait_to_impl_assoc_map);
831    let impl_assoc_id = *trait_to_impl_assoc_map.get(&trait_assoc_id)?;
832    debug!(?impl_assoc_id);
833    Some(tcx.associated_item(impl_assoc_id))
834}
835
836/// Given a type, return all trait impls in scope in `module` for that type.
837/// Returns a set of pairs of `(impl_id, trait_id)`.
838///
839/// NOTE: this cannot be a query because more traits could be available when more crates are compiled!
840/// So it is not stable to serialize cross-crate.
841#[instrument(level = "debug", skip(cx))]
842fn trait_impls_for<'a>(
843    cx: &mut DocContext<'a>,
844    ty: Ty<'a>,
845    module: DefId,
846) -> FxIndexSet<(DefId, DefId)> {
847    let tcx = cx.tcx;
848    let mut impls = FxIndexSet::default();
849
850    for &trait_ in tcx.doc_link_traits_in_scope(module) {
851        tcx.for_each_relevant_impl(trait_, ty, |impl_| {
852            let trait_ref = tcx.impl_trait_ref(impl_).expect("this is not an inherent impl");
853            // Check if these are the same type.
854            let impl_type = trait_ref.skip_binder().self_ty();
855            trace!(
856                "comparing type {impl_type} with kind {kind:?} against type {ty:?}",
857                kind = impl_type.kind(),
858            );
859            // Fast path: if this is a primitive simple `==` will work
860            // NOTE: the `match` is necessary; see #92662.
861            // this allows us to ignore generics because the user input
862            // may not include the generic placeholders
863            // e.g. this allows us to match Foo (user comment) with Foo<T> (actual type)
864            let saw_impl = impl_type == ty
865                || match (impl_type.kind(), ty.kind()) {
866                    (ty::Adt(impl_def, _), ty::Adt(ty_def, _)) => {
867                        debug!("impl def_id: {:?}, ty def_id: {:?}", impl_def.did(), ty_def.did());
868                        impl_def.did() == ty_def.did()
869                    }
870                    _ => false,
871                };
872
873            if saw_impl {
874                impls.insert((impl_, trait_));
875            }
876        });
877    }
878
879    impls
880}
881
882/// Check for resolve collisions between a trait and its derive.
883///
884/// These are common and we should just resolve to the trait in that case.
885fn is_derive_trait_collision<T>(ns: &PerNS<Result<Vec<(Res, T)>, ResolutionFailure<'_>>>) -> bool {
886    if let (Ok(type_ns), Ok(macro_ns)) = (&ns.type_ns, &ns.macro_ns) {
887        type_ns.iter().any(|(res, _)| matches!(res, Res::Def(DefKind::Trait, _)))
888            && macro_ns
889                .iter()
890                .any(|(res, _)| matches!(res, Res::Def(DefKind::Macro(MacroKind::Derive), _)))
891    } else {
892        false
893    }
894}
895
896impl DocVisitor<'_> for LinkCollector<'_, '_> {
897    fn visit_item(&mut self, item: &Item) {
898        self.resolve_links(item);
899        self.visit_item_recur(item)
900    }
901}
902
903enum PreprocessingError {
904    /// User error: `[std#x#y]` is not valid
905    MultipleAnchors,
906    Disambiguator(MarkdownLinkRange, String),
907    MalformedGenerics(MalformedGenerics, String),
908}
909
910impl PreprocessingError {
911    fn report(&self, cx: &DocContext<'_>, diag_info: DiagnosticInfo<'_>) {
912        match self {
913            PreprocessingError::MultipleAnchors => report_multiple_anchors(cx, diag_info),
914            PreprocessingError::Disambiguator(range, msg) => {
915                disambiguator_error(cx, diag_info, range.clone(), msg.clone())
916            }
917            PreprocessingError::MalformedGenerics(err, path_str) => {
918                report_malformed_generics(cx, diag_info, *err, path_str)
919            }
920        }
921    }
922}
923
924#[derive(Clone)]
925struct PreprocessingInfo {
926    path_str: Box<str>,
927    disambiguator: Option<Disambiguator>,
928    extra_fragment: Option<String>,
929    link_text: Box<str>,
930}
931
932// Not a typedef to avoid leaking several private structures from this module.
933pub(crate) struct PreprocessedMarkdownLink(
934    Result<PreprocessingInfo, PreprocessingError>,
935    MarkdownLink,
936);
937
938/// Returns:
939/// - `None` if the link should be ignored.
940/// - `Some(Err)` if the link should emit an error
941/// - `Some(Ok)` if the link is valid
942///
943/// `link_buffer` is needed for lifetime reasons; it will always be overwritten and the contents ignored.
944fn preprocess_link(
945    ori_link: &MarkdownLink,
946    dox: &str,
947) -> Option<Result<PreprocessingInfo, PreprocessingError>> {
948    // [] is mostly likely not supposed to be a link
949    if ori_link.link.is_empty() {
950        return None;
951    }
952
953    // Bail early for real links.
954    if ori_link.link.contains('/') {
955        return None;
956    }
957
958    let stripped = ori_link.link.replace('`', "");
959    let mut parts = stripped.split('#');
960
961    let link = parts.next().unwrap();
962    let link = link.trim();
963    if link.is_empty() {
964        // This is an anchor to an element of the current page, nothing to do in here!
965        return None;
966    }
967    let extra_fragment = parts.next();
968    if parts.next().is_some() {
969        // A valid link can't have multiple #'s
970        return Some(Err(PreprocessingError::MultipleAnchors));
971    }
972
973    // Parse and strip the disambiguator from the link, if present.
974    let (disambiguator, path_str, link_text) = match Disambiguator::from_str(link) {
975        Ok(Some((d, path, link_text))) => (Some(d), path.trim(), link_text.trim()),
976        Ok(None) => (None, link, link),
977        Err((err_msg, relative_range)) => {
978            // Only report error if we would not have ignored this link. See issue #83859.
979            if !should_ignore_link_with_disambiguators(link) {
980                let disambiguator_range = match range_between_backticks(&ori_link.range, dox) {
981                    MarkdownLinkRange::Destination(no_backticks_range) => {
982                        MarkdownLinkRange::Destination(
983                            (no_backticks_range.start + relative_range.start)
984                                ..(no_backticks_range.start + relative_range.end),
985                        )
986                    }
987                    mdlr @ MarkdownLinkRange::WholeLink(_) => mdlr,
988                };
989                return Some(Err(PreprocessingError::Disambiguator(disambiguator_range, err_msg)));
990            } else {
991                return None;
992            }
993        }
994    };
995
996    if should_ignore_link(path_str) {
997        return None;
998    }
999
1000    // Strip generics from the path.
1001    let path_str = match strip_generics_from_path(path_str) {
1002        Ok(path) => path,
1003        Err(err) => {
1004            debug!("link has malformed generics: {path_str}");
1005            return Some(Err(PreprocessingError::MalformedGenerics(err, path_str.to_owned())));
1006        }
1007    };
1008
1009    // Sanity check to make sure we don't have any angle brackets after stripping generics.
1010    assert!(!path_str.contains(['<', '>'].as_slice()));
1011
1012    // The link is not an intra-doc link if it still contains spaces after stripping generics.
1013    if path_str.contains(' ') {
1014        return None;
1015    }
1016
1017    Some(Ok(PreprocessingInfo {
1018        path_str,
1019        disambiguator,
1020        extra_fragment: extra_fragment.map(|frag| frag.to_owned()),
1021        link_text: Box::<str>::from(link_text),
1022    }))
1023}
1024
1025fn preprocessed_markdown_links(s: &str) -> Vec<PreprocessedMarkdownLink> {
1026    markdown_links(s, |link| {
1027        preprocess_link(&link, s).map(|pp_link| PreprocessedMarkdownLink(pp_link, link))
1028    })
1029}
1030
1031impl LinkCollector<'_, '_> {
1032    #[instrument(level = "debug", skip_all)]
1033    fn resolve_links(&mut self, item: &Item) {
1034        if !self.cx.render_options.document_private
1035            && let Some(def_id) = item.item_id.as_def_id()
1036            && let Some(def_id) = def_id.as_local()
1037            && !self.cx.tcx.effective_visibilities(()).is_exported(def_id)
1038            && !has_primitive_or_keyword_docs(&item.attrs.other_attrs)
1039        {
1040            // Skip link resolution for non-exported items.
1041            return;
1042        }
1043
1044        // We want to resolve in the lexical scope of the documentation.
1045        // In the presence of re-exports, this is not the same as the module of the item.
1046        // Rather than merging all documentation into one, resolve it one attribute at a time
1047        // so we know which module it came from.
1048        for (item_id, doc) in prepare_to_doc_link_resolution(&item.attrs.doc_strings) {
1049            if !may_have_doc_links(&doc) {
1050                continue;
1051            }
1052            debug!("combined_docs={doc}");
1053            // NOTE: if there are links that start in one crate and end in another, this will not resolve them.
1054            // This is a degenerate case and it's not supported by rustdoc.
1055            let item_id = item_id.unwrap_or_else(|| item.item_id.expect_def_id());
1056            let module_id = match self.cx.tcx.def_kind(item_id) {
1057                DefKind::Mod if item.inner_docs(self.cx.tcx) => item_id,
1058                _ => find_nearest_parent_module(self.cx.tcx, item_id).unwrap(),
1059            };
1060            for md_link in preprocessed_markdown_links(&doc) {
1061                let link = self.resolve_link(&doc, item, item_id, module_id, &md_link);
1062                if let Some(link) = link {
1063                    self.cx.cache.intra_doc_links.entry(item.item_id).or_default().insert(link);
1064                }
1065            }
1066        }
1067    }
1068
1069    pub(crate) fn save_link(&mut self, item_id: ItemId, link: ItemLink) {
1070        self.cx.cache.intra_doc_links.entry(item_id).or_default().insert(link);
1071    }
1072
1073    /// This is the entry point for resolving an intra-doc link.
1074    ///
1075    /// FIXME(jynelson): this is way too many arguments
1076    fn resolve_link(
1077        &mut self,
1078        dox: &String,
1079        item: &Item,
1080        item_id: DefId,
1081        module_id: DefId,
1082        PreprocessedMarkdownLink(pp_link, ori_link): &PreprocessedMarkdownLink,
1083    ) -> Option<ItemLink> {
1084        trace!("considering link '{}'", ori_link.link);
1085
1086        let diag_info = DiagnosticInfo {
1087            item,
1088            dox,
1089            ori_link: &ori_link.link,
1090            link_range: ori_link.range.clone(),
1091        };
1092        let PreprocessingInfo { path_str, disambiguator, extra_fragment, link_text } =
1093            pp_link.as_ref().map_err(|err| err.report(self.cx, diag_info.clone())).ok()?;
1094        let disambiguator = *disambiguator;
1095
1096        let mut resolved = self.resolve_with_disambiguator_cached(
1097            ResolutionInfo {
1098                item_id,
1099                module_id,
1100                dis: disambiguator,
1101                path_str: path_str.clone(),
1102                extra_fragment: extra_fragment.clone(),
1103            },
1104            diag_info.clone(), // this struct should really be Copy, but Range is not :(
1105            // For reference-style links we want to report only one error so unsuccessful
1106            // resolutions are cached, for other links we want to report an error every
1107            // time so they are not cached.
1108            matches!(ori_link.kind, LinkType::Reference | LinkType::Shortcut),
1109        )?;
1110
1111        if resolved.len() > 1 {
1112            let links = AmbiguousLinks {
1113                link_text: link_text.clone(),
1114                diag_info: diag_info.into(),
1115                resolved,
1116            };
1117
1118            self.ambiguous_links
1119                .entry((item.item_id, path_str.to_string()))
1120                .or_default()
1121                .push(links);
1122            None
1123        } else if let Some((res, fragment)) = resolved.pop() {
1124            self.compute_link(res, fragment, path_str, disambiguator, diag_info, link_text)
1125        } else {
1126            None
1127        }
1128    }
1129
1130    /// Returns `true` if a link could be generated from the given intra-doc information.
1131    ///
1132    /// This is a very light version of `format::href_with_root_path` since we're only interested
1133    /// about whether we can generate a link to an item or not.
1134    ///
1135    /// * If `original_did` is local, then we check if the item is reexported or public.
1136    /// * If `original_did` is not local, then we check if the crate it comes from is a direct
1137    ///   public dependency.
1138    fn validate_link(&self, original_did: DefId) -> bool {
1139        let tcx = self.cx.tcx;
1140        let def_kind = tcx.def_kind(original_did);
1141        let did = match def_kind {
1142            DefKind::AssocTy | DefKind::AssocFn | DefKind::AssocConst | DefKind::Variant => {
1143                // documented on their parent's page
1144                tcx.parent(original_did)
1145            }
1146            // If this a constructor, we get the parent (either a struct or a variant) and then
1147            // generate the link for this item.
1148            DefKind::Ctor(..) => return self.validate_link(tcx.parent(original_did)),
1149            DefKind::ExternCrate => {
1150                // Link to the crate itself, not the `extern crate` item.
1151                if let Some(local_did) = original_did.as_local() {
1152                    tcx.extern_mod_stmt_cnum(local_did).unwrap_or(LOCAL_CRATE).as_def_id()
1153                } else {
1154                    original_did
1155                }
1156            }
1157            _ => original_did,
1158        };
1159
1160        let cache = &self.cx.cache;
1161        if !original_did.is_local()
1162            && !cache.effective_visibilities.is_directly_public(tcx, did)
1163            && !cache.document_private
1164            && !cache.primitive_locations.values().any(|&id| id == did)
1165        {
1166            return false;
1167        }
1168
1169        cache.paths.get(&did).is_some()
1170            || cache.external_paths.contains_key(&did)
1171            || !did.is_local()
1172    }
1173
1174    #[allow(rustc::potential_query_instability)]
1175    pub(crate) fn resolve_ambiguities(&mut self) {
1176        let mut ambiguous_links = mem::take(&mut self.ambiguous_links);
1177
1178        for ((item_id, path_str), info_items) in ambiguous_links.iter_mut() {
1179            for info in info_items {
1180                info.resolved.retain(|(res, _)| match res {
1181                    Res::Def(_, def_id) => self.validate_link(*def_id),
1182                    // Primitive types are always valid.
1183                    Res::Primitive(_) => true,
1184                });
1185                let diag_info = info.diag_info.into_info();
1186                match info.resolved.len() {
1187                    1 => {
1188                        let (res, fragment) = info.resolved.pop().unwrap();
1189                        if let Some(link) = self.compute_link(
1190                            res,
1191                            fragment,
1192                            path_str,
1193                            None,
1194                            diag_info,
1195                            &info.link_text,
1196                        ) {
1197                            self.save_link(*item_id, link);
1198                        }
1199                    }
1200                    0 => {
1201                        report_diagnostic(
1202                            self.cx.tcx,
1203                            BROKEN_INTRA_DOC_LINKS,
1204                            format!("all items matching `{path_str}` are private or doc(hidden)"),
1205                            &diag_info,
1206                            |diag, sp, _| {
1207                                if let Some(sp) = sp {
1208                                    diag.span_label(sp, "unresolved link");
1209                                } else {
1210                                    diag.note("unresolved link");
1211                                }
1212                            },
1213                        );
1214                    }
1215                    _ => {
1216                        let candidates = info
1217                            .resolved
1218                            .iter()
1219                            .map(|(res, fragment)| {
1220                                let def_id = if let Some(UrlFragment::Item(def_id)) = fragment {
1221                                    Some(*def_id)
1222                                } else {
1223                                    None
1224                                };
1225                                (*res, def_id)
1226                            })
1227                            .collect::<Vec<_>>();
1228                        ambiguity_error(self.cx, &diag_info, path_str, &candidates, true);
1229                    }
1230                }
1231            }
1232        }
1233    }
1234
1235    fn compute_link(
1236        &mut self,
1237        mut res: Res,
1238        fragment: Option<UrlFragment>,
1239        path_str: &str,
1240        disambiguator: Option<Disambiguator>,
1241        diag_info: DiagnosticInfo<'_>,
1242        link_text: &Box<str>,
1243    ) -> Option<ItemLink> {
1244        // Check for a primitive which might conflict with a module
1245        // Report the ambiguity and require that the user specify which one they meant.
1246        // FIXME: could there ever be a primitive not in the type namespace?
1247        if matches!(
1248            disambiguator,
1249            None | Some(Disambiguator::Namespace(Namespace::TypeNS) | Disambiguator::Primitive)
1250        ) && !matches!(res, Res::Primitive(_))
1251        {
1252            if let Some(prim) = resolve_primitive(path_str, TypeNS) {
1253                // `prim@char`
1254                if matches!(disambiguator, Some(Disambiguator::Primitive)) {
1255                    res = prim;
1256                } else {
1257                    // `[char]` when a `char` module is in scope
1258                    let candidates = &[(res, res.def_id(self.cx.tcx)), (prim, None)];
1259                    ambiguity_error(self.cx, &diag_info, path_str, candidates, true);
1260                    return None;
1261                }
1262            }
1263        }
1264
1265        match res {
1266            Res::Primitive(_) => {
1267                if let Some(UrlFragment::Item(id)) = fragment {
1268                    // We're actually resolving an associated item of a primitive, so we need to
1269                    // verify the disambiguator (if any) matches the type of the associated item.
1270                    // This case should really follow the same flow as the `Res::Def` branch below,
1271                    // but attempting to add a call to `clean::register_res` causes an ICE. @jyn514
1272                    // thinks `register_res` is only needed for cross-crate re-exports, but Rust
1273                    // doesn't allow statements like `use str::trim;`, making this a (hopefully)
1274                    // valid omission. See https://github.com/rust-lang/rust/pull/80660#discussion_r551585677
1275                    // for discussion on the matter.
1276                    let kind = self.cx.tcx.def_kind(id);
1277                    self.verify_disambiguator(path_str, kind, id, disambiguator, &diag_info)?;
1278                } else {
1279                    match disambiguator {
1280                        Some(Disambiguator::Primitive | Disambiguator::Namespace(_)) | None => {}
1281                        Some(other) => {
1282                            self.report_disambiguator_mismatch(path_str, other, res, &diag_info);
1283                            return None;
1284                        }
1285                    }
1286                }
1287
1288                res.def_id(self.cx.tcx).map(|page_id| ItemLink {
1289                    link: Box::<str>::from(diag_info.ori_link),
1290                    link_text: link_text.clone(),
1291                    page_id,
1292                    fragment,
1293                })
1294            }
1295            Res::Def(kind, id) => {
1296                let (kind_for_dis, id_for_dis) = if let Some(UrlFragment::Item(id)) = fragment {
1297                    (self.cx.tcx.def_kind(id), id)
1298                } else {
1299                    (kind, id)
1300                };
1301                self.verify_disambiguator(
1302                    path_str,
1303                    kind_for_dis,
1304                    id_for_dis,
1305                    disambiguator,
1306                    &diag_info,
1307                )?;
1308
1309                let page_id = clean::register_res(self.cx, rustc_hir::def::Res::Def(kind, id));
1310                Some(ItemLink {
1311                    link: Box::<str>::from(diag_info.ori_link),
1312                    link_text: link_text.clone(),
1313                    page_id,
1314                    fragment,
1315                })
1316            }
1317        }
1318    }
1319
1320    fn verify_disambiguator(
1321        &self,
1322        path_str: &str,
1323        kind: DefKind,
1324        id: DefId,
1325        disambiguator: Option<Disambiguator>,
1326        diag_info: &DiagnosticInfo<'_>,
1327    ) -> Option<()> {
1328        debug!("intra-doc link to {path_str} resolved to {:?}", (kind, id));
1329
1330        // Disallow e.g. linking to enums with `struct@`
1331        debug!("saw kind {kind:?} with disambiguator {disambiguator:?}");
1332        match (kind, disambiguator) {
1333                | (DefKind::Const | DefKind::ConstParam | DefKind::AssocConst | DefKind::AnonConst, Some(Disambiguator::Kind(DefKind::Const)))
1334                // NOTE: this allows 'method' to mean both normal functions and associated functions
1335                // This can't cause ambiguity because both are in the same namespace.
1336                | (DefKind::Fn | DefKind::AssocFn, Some(Disambiguator::Kind(DefKind::Fn)))
1337                // These are namespaces; allow anything in the namespace to match
1338                | (_, Some(Disambiguator::Namespace(_)))
1339                // If no disambiguator given, allow anything
1340                | (_, None)
1341                // All of these are valid, so do nothing
1342                => {}
1343                (actual, Some(Disambiguator::Kind(expected))) if actual == expected => {}
1344                (_, Some(specified @ Disambiguator::Kind(_) | specified @ Disambiguator::Primitive)) => {
1345                    self.report_disambiguator_mismatch(path_str, specified, Res::Def(kind, id), diag_info);
1346                    return None;
1347                }
1348            }
1349
1350        // item can be non-local e.g. when using `#[rustc_doc_primitive = "pointer"]`
1351        if let Some(dst_id) = id.as_local()
1352            && let Some(src_id) = diag_info.item.item_id.expect_def_id().as_local()
1353            && self.cx.tcx.effective_visibilities(()).is_exported(src_id)
1354            && !self.cx.tcx.effective_visibilities(()).is_exported(dst_id)
1355        {
1356            privacy_error(self.cx, diag_info, path_str);
1357        }
1358
1359        Some(())
1360    }
1361
1362    fn report_disambiguator_mismatch(
1363        &self,
1364        path_str: &str,
1365        specified: Disambiguator,
1366        resolved: Res,
1367        diag_info: &DiagnosticInfo<'_>,
1368    ) {
1369        // The resolved item did not match the disambiguator; give a better error than 'not found'
1370        let msg = format!("incompatible link kind for `{path_str}`");
1371        let callback = |diag: &mut Diag<'_, ()>, sp: Option<rustc_span::Span>, link_range| {
1372            let note = format!(
1373                "this link resolved to {} {}, which is not {} {}",
1374                resolved.article(),
1375                resolved.descr(),
1376                specified.article(),
1377                specified.descr(),
1378            );
1379            if let Some(sp) = sp {
1380                diag.span_label(sp, note);
1381            } else {
1382                diag.note(note);
1383            }
1384            suggest_disambiguator(resolved, diag, path_str, link_range, sp, diag_info);
1385        };
1386        report_diagnostic(self.cx.tcx, BROKEN_INTRA_DOC_LINKS, msg, diag_info, callback);
1387    }
1388
1389    fn report_rawptr_assoc_feature_gate(
1390        &self,
1391        dox: &str,
1392        ori_link: &MarkdownLinkRange,
1393        item: &Item,
1394    ) {
1395        let span = source_span_for_markdown_range(
1396            self.cx.tcx,
1397            dox,
1398            ori_link.inner_range(),
1399            &item.attrs.doc_strings,
1400        )
1401        .unwrap_or_else(|| item.attr_span(self.cx.tcx));
1402        rustc_session::parse::feature_err(
1403            self.cx.tcx.sess,
1404            sym::intra_doc_pointers,
1405            span,
1406            "linking to associated items of raw pointers is experimental",
1407        )
1408        .with_note("rustdoc does not allow disambiguating between `*const` and `*mut`, and pointers are unstable until it does")
1409        .emit();
1410    }
1411
1412    fn resolve_with_disambiguator_cached(
1413        &mut self,
1414        key: ResolutionInfo,
1415        diag: DiagnosticInfo<'_>,
1416        // If errors are cached then they are only reported on first occurrence
1417        // which we want in some cases but not in others.
1418        cache_errors: bool,
1419    ) -> Option<Vec<(Res, Option<UrlFragment>)>> {
1420        if let Some(res) = self.visited_links.get(&key)
1421            && (res.is_some() || cache_errors)
1422        {
1423            return res.clone().map(|r| vec![r]);
1424        }
1425
1426        let mut candidates = self.resolve_with_disambiguator(&key, diag.clone());
1427
1428        // FIXME: it would be nice to check that the feature gate was enabled in the original crate, not just ignore it altogether.
1429        // However I'm not sure how to check that across crates.
1430        if let Some(candidate) = candidates.first()
1431            && candidate.0 == Res::Primitive(PrimitiveType::RawPointer)
1432            && key.path_str.contains("::")
1433        // We only want to check this if this is an associated item.
1434        {
1435            if key.item_id.is_local() && !self.cx.tcx.features().intra_doc_pointers() {
1436                self.report_rawptr_assoc_feature_gate(diag.dox, &diag.link_range, diag.item);
1437                return None;
1438            } else {
1439                candidates = vec![*candidate];
1440            }
1441        }
1442
1443        // If there are multiple items with the same "kind" (for example, both "associated types")
1444        // and after removing duplicated kinds, only one remains, the `ambiguity_error` function
1445        // won't emit an error. So at this point, we can just take the first candidate as it was
1446        // the first retrieved and use it to generate the link.
1447        if let [candidate, _candidate2, ..] = *candidates
1448            && !ambiguity_error(self.cx, &diag, &key.path_str, &candidates, false)
1449        {
1450            candidates = vec![candidate];
1451        }
1452
1453        let mut out = Vec::with_capacity(candidates.len());
1454        for (res, def_id) in candidates {
1455            let fragment = match (&key.extra_fragment, def_id) {
1456                (Some(_), Some(def_id)) => {
1457                    report_anchor_conflict(self.cx, diag, def_id);
1458                    return None;
1459                }
1460                (Some(u_frag), None) => Some(UrlFragment::UserWritten(u_frag.clone())),
1461                (None, Some(def_id)) => Some(UrlFragment::Item(def_id)),
1462                (None, None) => None,
1463            };
1464            out.push((res, fragment));
1465        }
1466        if let [r] = out.as_slice() {
1467            self.visited_links.insert(key, Some(r.clone()));
1468        } else if cache_errors {
1469            self.visited_links.insert(key, None);
1470        }
1471        Some(out)
1472    }
1473
1474    /// After parsing the disambiguator, resolve the main part of the link.
1475    fn resolve_with_disambiguator(
1476        &mut self,
1477        key: &ResolutionInfo,
1478        diag: DiagnosticInfo<'_>,
1479    ) -> Vec<(Res, Option<DefId>)> {
1480        let disambiguator = key.dis;
1481        let path_str = &key.path_str;
1482        let item_id = key.item_id;
1483        let module_id = key.module_id;
1484
1485        match disambiguator.map(Disambiguator::ns) {
1486            Some(expected_ns) => {
1487                match self.resolve(path_str, expected_ns, disambiguator, item_id, module_id) {
1488                    Ok(candidates) => candidates,
1489                    Err(err) => {
1490                        // We only looked in one namespace. Try to give a better error if possible.
1491                        // FIXME: really it should be `resolution_failure` that does this, not `resolve_with_disambiguator`.
1492                        // See https://github.com/rust-lang/rust/pull/76955#discussion_r493953382 for a good approach.
1493                        let mut err = ResolutionFailure::NotResolved(err);
1494                        for other_ns in [TypeNS, ValueNS, MacroNS] {
1495                            if other_ns != expected_ns
1496                                && let Ok(&[res, ..]) = self
1497                                    .resolve(path_str, other_ns, None, item_id, module_id)
1498                                    .as_deref()
1499                            {
1500                                err = ResolutionFailure::WrongNamespace {
1501                                    res: full_res(self.cx.tcx, res),
1502                                    expected_ns,
1503                                };
1504                                break;
1505                            }
1506                        }
1507                        resolution_failure(self, diag, path_str, disambiguator, smallvec![err]);
1508                        vec![]
1509                    }
1510                }
1511            }
1512            None => {
1513                // Try everything!
1514                let mut candidate = |ns| {
1515                    self.resolve(path_str, ns, None, item_id, module_id)
1516                        .map_err(ResolutionFailure::NotResolved)
1517                };
1518
1519                let candidates = PerNS {
1520                    macro_ns: candidate(MacroNS),
1521                    type_ns: candidate(TypeNS),
1522                    value_ns: candidate(ValueNS).and_then(|v_res| {
1523                        for (res, _) in v_res.iter() {
1524                            // Constructors are picked up in the type namespace.
1525                            if let Res::Def(DefKind::Ctor(..), _) = res {
1526                                return Err(ResolutionFailure::WrongNamespace {
1527                                    res: *res,
1528                                    expected_ns: TypeNS,
1529                                });
1530                            }
1531                        }
1532                        Ok(v_res)
1533                    }),
1534                };
1535
1536                let len = candidates
1537                    .iter()
1538                    .fold(0, |acc, res| if let Ok(res) = res { acc + res.len() } else { acc });
1539
1540                if len == 0 {
1541                    resolution_failure(
1542                        self,
1543                        diag,
1544                        path_str,
1545                        disambiguator,
1546                        candidates.into_iter().filter_map(|res| res.err()).collect(),
1547                    );
1548                    vec![]
1549                } else if len == 1 {
1550                    candidates.into_iter().filter_map(|res| res.ok()).flatten().collect::<Vec<_>>()
1551                } else {
1552                    let has_derive_trait_collision = is_derive_trait_collision(&candidates);
1553                    if len == 2 && has_derive_trait_collision {
1554                        candidates.type_ns.unwrap()
1555                    } else {
1556                        // If we're reporting an ambiguity, don't mention the namespaces that failed
1557                        let mut candidates = candidates.map(|candidate| candidate.ok());
1558                        // If there a collision between a trait and a derive, we ignore the derive.
1559                        if has_derive_trait_collision {
1560                            candidates.macro_ns = None;
1561                        }
1562                        candidates.into_iter().flatten().flatten().collect::<Vec<_>>()
1563                    }
1564                }
1565            }
1566        }
1567    }
1568}
1569
1570/// Get the section of a link between the backticks,
1571/// or the whole link if there aren't any backticks.
1572///
1573/// For example:
1574///
1575/// ```text
1576/// [`Foo`]
1577///   ^^^
1578/// ```
1579///
1580/// This function does nothing if `ori_link.range` is a `MarkdownLinkRange::WholeLink`.
1581fn range_between_backticks(ori_link_range: &MarkdownLinkRange, dox: &str) -> MarkdownLinkRange {
1582    let range = match ori_link_range {
1583        mdlr @ MarkdownLinkRange::WholeLink(_) => return mdlr.clone(),
1584        MarkdownLinkRange::Destination(inner) => inner.clone(),
1585    };
1586    let ori_link_text = &dox[range.clone()];
1587    let after_first_backtick_group = ori_link_text.bytes().position(|b| b != b'`').unwrap_or(0);
1588    let before_second_backtick_group = ori_link_text
1589        .bytes()
1590        .skip(after_first_backtick_group)
1591        .position(|b| b == b'`')
1592        .unwrap_or(ori_link_text.len());
1593    MarkdownLinkRange::Destination(
1594        (range.start + after_first_backtick_group)..(range.start + before_second_backtick_group),
1595    )
1596}
1597
1598/// Returns true if we should ignore `link` due to it being unlikely
1599/// that it is an intra-doc link. `link` should still have disambiguators
1600/// if there were any.
1601///
1602/// The difference between this and [`should_ignore_link()`] is that this
1603/// check should only be used on links that still have disambiguators.
1604fn should_ignore_link_with_disambiguators(link: &str) -> bool {
1605    link.contains(|ch: char| !(ch.is_alphanumeric() || ":_<>, !*&;@()".contains(ch)))
1606}
1607
1608/// Returns true if we should ignore `path_str` due to it being unlikely
1609/// that it is an intra-doc link.
1610fn should_ignore_link(path_str: &str) -> bool {
1611    path_str.contains(|ch: char| !(ch.is_alphanumeric() || ":_<>, !*&;".contains(ch)))
1612}
1613
1614#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
1615/// Disambiguators for a link.
1616enum Disambiguator {
1617    /// `prim@`
1618    ///
1619    /// This is buggy, see <https://github.com/rust-lang/rust/pull/77875#discussion_r503583103>
1620    Primitive,
1621    /// `struct@` or `f()`
1622    Kind(DefKind),
1623    /// `type@`
1624    Namespace(Namespace),
1625}
1626
1627impl Disambiguator {
1628    /// Given a link, parse and return `(disambiguator, path_str, link_text)`.
1629    ///
1630    /// This returns `Ok(Some(...))` if a disambiguator was found,
1631    /// `Ok(None)` if no disambiguator was found, or `Err(...)`
1632    /// if there was a problem with the disambiguator.
1633    fn from_str(link: &str) -> Result<Option<(Self, &str, &str)>, (String, Range<usize>)> {
1634        use Disambiguator::{Kind, Namespace as NS, Primitive};
1635
1636        let suffixes = [
1637            // If you update this list, please also update the relevant rustdoc book section!
1638            ("!()", DefKind::Macro(MacroKind::Bang)),
1639            ("!{}", DefKind::Macro(MacroKind::Bang)),
1640            ("![]", DefKind::Macro(MacroKind::Bang)),
1641            ("()", DefKind::Fn),
1642            ("!", DefKind::Macro(MacroKind::Bang)),
1643        ];
1644
1645        if let Some(idx) = link.find('@') {
1646            let (prefix, rest) = link.split_at(idx);
1647            let d = match prefix {
1648                // If you update this list, please also update the relevant rustdoc book section!
1649                "struct" => Kind(DefKind::Struct),
1650                "enum" => Kind(DefKind::Enum),
1651                "trait" => Kind(DefKind::Trait),
1652                "union" => Kind(DefKind::Union),
1653                "module" | "mod" => Kind(DefKind::Mod),
1654                "const" | "constant" => Kind(DefKind::Const),
1655                "static" => Kind(DefKind::Static {
1656                    mutability: Mutability::Not,
1657                    nested: false,
1658                    safety: Safety::Safe,
1659                }),
1660                "function" | "fn" | "method" => Kind(DefKind::Fn),
1661                "derive" => Kind(DefKind::Macro(MacroKind::Derive)),
1662                "field" => Kind(DefKind::Field),
1663                "variant" => Kind(DefKind::Variant),
1664                "type" => NS(Namespace::TypeNS),
1665                "value" => NS(Namespace::ValueNS),
1666                "macro" => NS(Namespace::MacroNS),
1667                "prim" | "primitive" => Primitive,
1668                _ => return Err((format!("unknown disambiguator `{prefix}`"), 0..idx)),
1669            };
1670
1671            for (suffix, kind) in suffixes {
1672                if let Some(path_str) = rest.strip_suffix(suffix) {
1673                    if d.ns() != Kind(kind).ns() {
1674                        return Err((
1675                            format!("unmatched disambiguator `{prefix}` and suffix `{suffix}`"),
1676                            0..idx,
1677                        ));
1678                    } else if path_str.len() > 1 {
1679                        // path_str != "@"
1680                        return Ok(Some((d, &path_str[1..], &rest[1..])));
1681                    }
1682                }
1683            }
1684
1685            Ok(Some((d, &rest[1..], &rest[1..])))
1686        } else {
1687            for (suffix, kind) in suffixes {
1688                // Avoid turning `!` or `()` into an empty string
1689                if let Some(path_str) = link.strip_suffix(suffix)
1690                    && !path_str.is_empty()
1691                {
1692                    return Ok(Some((Kind(kind), path_str, link)));
1693                }
1694            }
1695            Ok(None)
1696        }
1697    }
1698
1699    fn ns(self) -> Namespace {
1700        match self {
1701            Self::Namespace(n) => n,
1702            // for purposes of link resolution, fields are in the value namespace.
1703            Self::Kind(DefKind::Field) => ValueNS,
1704            Self::Kind(k) => {
1705                k.ns().expect("only DefKinds with a valid namespace can be disambiguators")
1706            }
1707            Self::Primitive => TypeNS,
1708        }
1709    }
1710
1711    fn article(self) -> &'static str {
1712        match self {
1713            Self::Namespace(_) => panic!("article() doesn't make sense for namespaces"),
1714            Self::Kind(k) => k.article(),
1715            Self::Primitive => "a",
1716        }
1717    }
1718
1719    fn descr(self) -> &'static str {
1720        match self {
1721            Self::Namespace(n) => n.descr(),
1722            // HACK(jynelson): the source of `DefKind::descr` only uses the DefId for
1723            // printing "module" vs "crate" so using the wrong ID is not a huge problem
1724            Self::Kind(k) => k.descr(CRATE_DEF_ID.to_def_id()),
1725            Self::Primitive => "builtin type",
1726        }
1727    }
1728}
1729
1730/// A suggestion to show in a diagnostic.
1731enum Suggestion {
1732    /// `struct@`
1733    Prefix(&'static str),
1734    /// `f()`
1735    Function,
1736    /// `m!`
1737    Macro,
1738}
1739
1740impl Suggestion {
1741    fn descr(&self) -> Cow<'static, str> {
1742        match self {
1743            Self::Prefix(x) => format!("prefix with `{x}@`").into(),
1744            Self::Function => "add parentheses".into(),
1745            Self::Macro => "add an exclamation mark".into(),
1746        }
1747    }
1748
1749    fn as_help(&self, path_str: &str) -> String {
1750        // FIXME: if this is an implied shortcut link, it's bad style to suggest `@`
1751        match self {
1752            Self::Prefix(prefix) => format!("{prefix}@{path_str}"),
1753            Self::Function => format!("{path_str}()"),
1754            Self::Macro => format!("{path_str}!"),
1755        }
1756    }
1757
1758    fn as_help_span(
1759        &self,
1760        ori_link: &str,
1761        sp: rustc_span::Span,
1762    ) -> Vec<(rustc_span::Span, String)> {
1763        let inner_sp = match ori_link.find('(') {
1764            Some(index) if index != 0 && ori_link.as_bytes()[index - 1] == b'\\' => {
1765                sp.with_hi(sp.lo() + BytePos((index - 1) as _))
1766            }
1767            Some(index) => sp.with_hi(sp.lo() + BytePos(index as _)),
1768            None => sp,
1769        };
1770        let inner_sp = match ori_link.find('!') {
1771            Some(index) if index != 0 && ori_link.as_bytes()[index - 1] == b'\\' => {
1772                sp.with_hi(sp.lo() + BytePos((index - 1) as _))
1773            }
1774            Some(index) => inner_sp.with_hi(inner_sp.lo() + BytePos(index as _)),
1775            None => inner_sp,
1776        };
1777        let inner_sp = match ori_link.find('@') {
1778            Some(index) if index != 0 && ori_link.as_bytes()[index - 1] == b'\\' => {
1779                sp.with_hi(sp.lo() + BytePos((index - 1) as _))
1780            }
1781            Some(index) => inner_sp.with_lo(inner_sp.lo() + BytePos(index as u32 + 1)),
1782            None => inner_sp,
1783        };
1784        match self {
1785            Self::Prefix(prefix) => {
1786                // FIXME: if this is an implied shortcut link, it's bad style to suggest `@`
1787                let mut sugg = vec![(sp.with_hi(inner_sp.lo()), format!("{prefix}@"))];
1788                if sp.hi() != inner_sp.hi() {
1789                    sugg.push((inner_sp.shrink_to_hi().with_hi(sp.hi()), String::new()));
1790                }
1791                sugg
1792            }
1793            Self::Function => {
1794                let mut sugg = vec![(inner_sp.shrink_to_hi().with_hi(sp.hi()), "()".to_string())];
1795                if sp.lo() != inner_sp.lo() {
1796                    sugg.push((inner_sp.shrink_to_lo().with_lo(sp.lo()), String::new()));
1797                }
1798                sugg
1799            }
1800            Self::Macro => {
1801                let mut sugg = vec![(inner_sp.shrink_to_hi(), "!".to_string())];
1802                if sp.lo() != inner_sp.lo() {
1803                    sugg.push((inner_sp.shrink_to_lo().with_lo(sp.lo()), String::new()));
1804                }
1805                sugg
1806            }
1807        }
1808    }
1809}
1810
1811/// Reports a diagnostic for an intra-doc link.
1812///
1813/// If no link range is provided, or the source span of the link cannot be determined, the span of
1814/// the entire documentation block is used for the lint. If a range is provided but the span
1815/// calculation fails, a note is added to the diagnostic pointing to the link in the markdown.
1816///
1817/// The `decorate` callback is invoked in all cases to allow further customization of the
1818/// diagnostic before emission. If the span of the link was able to be determined, the second
1819/// parameter of the callback will contain it, and the primary span of the diagnostic will be set
1820/// to it.
1821fn report_diagnostic(
1822    tcx: TyCtxt<'_>,
1823    lint: &'static Lint,
1824    msg: impl Into<DiagMessage> + Display,
1825    DiagnosticInfo { item, ori_link: _, dox, link_range }: &DiagnosticInfo<'_>,
1826    decorate: impl FnOnce(&mut Diag<'_, ()>, Option<rustc_span::Span>, MarkdownLinkRange),
1827) {
1828    let Some(hir_id) = DocContext::as_local_hir_id(tcx, item.item_id) else {
1829        // If non-local, no need to check anything.
1830        info!("ignoring warning from parent crate: {msg}");
1831        return;
1832    };
1833
1834    let sp = item.attr_span(tcx);
1835
1836    tcx.node_span_lint(lint, hir_id, sp, |lint| {
1837        lint.primary_message(msg);
1838
1839        let (span, link_range) = match link_range {
1840            MarkdownLinkRange::Destination(md_range) => {
1841                let mut md_range = md_range.clone();
1842                let sp =
1843                    source_span_for_markdown_range(tcx, dox, &md_range, &item.attrs.doc_strings)
1844                        .map(|mut sp| {
1845                            while dox.as_bytes().get(md_range.start) == Some(&b' ')
1846                                || dox.as_bytes().get(md_range.start) == Some(&b'`')
1847                            {
1848                                md_range.start += 1;
1849                                sp = sp.with_lo(sp.lo() + BytePos(1));
1850                            }
1851                            while dox.as_bytes().get(md_range.end - 1) == Some(&b' ')
1852                                || dox.as_bytes().get(md_range.end - 1) == Some(&b'`')
1853                            {
1854                                md_range.end -= 1;
1855                                sp = sp.with_hi(sp.hi() - BytePos(1));
1856                            }
1857                            sp
1858                        });
1859                (sp, MarkdownLinkRange::Destination(md_range))
1860            }
1861            MarkdownLinkRange::WholeLink(md_range) => (
1862                source_span_for_markdown_range(tcx, dox, md_range, &item.attrs.doc_strings),
1863                link_range.clone(),
1864            ),
1865        };
1866
1867        if let Some(sp) = span {
1868            lint.span(sp);
1869        } else {
1870            // blah blah blah\nblah\nblah [blah] blah blah\nblah blah
1871            //                       ^     ~~~~
1872            //                       |     link_range
1873            //                       last_new_line_offset
1874            let md_range = link_range.inner_range().clone();
1875            let last_new_line_offset = dox[..md_range.start].rfind('\n').map_or(0, |n| n + 1);
1876            let line = dox[last_new_line_offset..].lines().next().unwrap_or("");
1877
1878            // Print the line containing the `md_range` and manually mark it with '^'s.
1879            lint.note(format!(
1880                "the link appears in this line:\n\n{line}\n\
1881                     {indicator: <before$}{indicator:^<found$}",
1882                indicator = "",
1883                before = md_range.start - last_new_line_offset,
1884                found = md_range.len(),
1885            ));
1886        }
1887
1888        decorate(lint, span, link_range);
1889    });
1890}
1891
1892/// Reports a link that failed to resolve.
1893///
1894/// This also tries to resolve any intermediate path segments that weren't
1895/// handled earlier. For example, if passed `Item::Crate(std)` and `path_str`
1896/// `std::io::Error::x`, this will resolve `std::io::Error`.
1897fn resolution_failure(
1898    collector: &mut LinkCollector<'_, '_>,
1899    diag_info: DiagnosticInfo<'_>,
1900    path_str: &str,
1901    disambiguator: Option<Disambiguator>,
1902    kinds: SmallVec<[ResolutionFailure<'_>; 3]>,
1903) {
1904    let tcx = collector.cx.tcx;
1905    report_diagnostic(
1906        tcx,
1907        BROKEN_INTRA_DOC_LINKS,
1908        format!("unresolved link to `{path_str}`"),
1909        &diag_info,
1910        |diag, sp, link_range| {
1911            let item = |res: Res| format!("the {} `{}`", res.descr(), res.name(tcx));
1912            let assoc_item_not_allowed = |res: Res| {
1913                let name = res.name(tcx);
1914                format!(
1915                    "`{name}` is {} {}, not a module or type, and cannot have associated items",
1916                    res.article(),
1917                    res.descr()
1918                )
1919            };
1920            // ignore duplicates
1921            let mut variants_seen = SmallVec::<[_; 3]>::new();
1922            for mut failure in kinds {
1923                let variant = mem::discriminant(&failure);
1924                if variants_seen.contains(&variant) {
1925                    continue;
1926                }
1927                variants_seen.push(variant);
1928
1929                if let ResolutionFailure::NotResolved(UnresolvedPath {
1930                    item_id,
1931                    module_id,
1932                    partial_res,
1933                    unresolved,
1934                }) = &mut failure
1935                {
1936                    use DefKind::*;
1937
1938                    let item_id = *item_id;
1939                    let module_id = *module_id;
1940
1941                    // Check if _any_ parent of the path gets resolved.
1942                    // If so, report it and say the first which failed; if not, say the first path segment didn't resolve.
1943                    let mut name = path_str;
1944                    'outer: loop {
1945                        // FIXME(jynelson): this might conflict with my `Self` fix in #76467
1946                        let Some((start, end)) = name.rsplit_once("::") else {
1947                            // avoid bug that marked [Quux::Z] as missing Z, not Quux
1948                            if partial_res.is_none() {
1949                                *unresolved = name.into();
1950                            }
1951                            break;
1952                        };
1953                        name = start;
1954                        for ns in [TypeNS, ValueNS, MacroNS] {
1955                            if let Ok(v_res) =
1956                                collector.resolve(start, ns, None, item_id, module_id)
1957                            {
1958                                debug!("found partial_res={v_res:?}");
1959                                if let Some(&res) = v_res.first() {
1960                                    *partial_res = Some(full_res(tcx, res));
1961                                    *unresolved = end.into();
1962                                    break 'outer;
1963                                }
1964                            }
1965                        }
1966                        *unresolved = end.into();
1967                    }
1968
1969                    let last_found_module = match *partial_res {
1970                        Some(Res::Def(DefKind::Mod, id)) => Some(id),
1971                        None => Some(module_id),
1972                        _ => None,
1973                    };
1974                    // See if this was a module: `[path]` or `[std::io::nope]`
1975                    if let Some(module) = last_found_module {
1976                        let note = if partial_res.is_some() {
1977                            // Part of the link resolved; e.g. `std::io::nonexistent`
1978                            let module_name = tcx.item_name(module);
1979                            format!("no item named `{unresolved}` in module `{module_name}`")
1980                        } else {
1981                            // None of the link resolved; e.g. `Notimported`
1982                            format!("no item named `{unresolved}` in scope")
1983                        };
1984                        if let Some(span) = sp {
1985                            diag.span_label(span, note);
1986                        } else {
1987                            diag.note(note);
1988                        }
1989
1990                        if !path_str.contains("::") {
1991                            if disambiguator.is_none_or(|d| d.ns() == MacroNS)
1992                                && collector
1993                                    .cx
1994                                    .tcx
1995                                    .resolutions(())
1996                                    .all_macro_rules
1997                                    .contains(&Symbol::intern(path_str))
1998                            {
1999                                diag.note(format!(
2000                                    "`macro_rules` named `{path_str}` exists in this crate, \
2001                                     but it is not in scope at this link's location"
2002                                ));
2003                            } else {
2004                                // If the link has `::` in it, assume it was meant to be an
2005                                // intra-doc link. Otherwise, the `[]` might be unrelated.
2006                                diag.help(
2007                                    "to escape `[` and `]` characters, \
2008                                           add '\\' before them like `\\[` or `\\]`",
2009                                );
2010                            }
2011                        }
2012
2013                        continue;
2014                    }
2015
2016                    // Otherwise, it must be an associated item or variant
2017                    let res = partial_res.expect("None case was handled by `last_found_module`");
2018                    let kind_did = match res {
2019                        Res::Def(kind, did) => Some((kind, did)),
2020                        Res::Primitive(_) => None,
2021                    };
2022                    let is_struct_variant = |did| {
2023                        if let ty::Adt(def, _) = tcx.type_of(did).instantiate_identity().kind()
2024                            && def.is_enum()
2025                            && let Some(variant) =
2026                                def.variants().iter().find(|v| v.name == res.name(tcx))
2027                        {
2028                            // ctor is `None` if variant is a struct
2029                            variant.ctor.is_none()
2030                        } else {
2031                            false
2032                        }
2033                    };
2034                    let path_description = if let Some((kind, did)) = kind_did {
2035                        match kind {
2036                            Mod | ForeignMod => "inner item",
2037                            Struct => "field or associated item",
2038                            Enum | Union => "variant or associated item",
2039                            Variant if is_struct_variant(did) => {
2040                                let variant = res.name(tcx);
2041                                let note = format!("variant `{variant}` has no such field");
2042                                if let Some(span) = sp {
2043                                    diag.span_label(span, note);
2044                                } else {
2045                                    diag.note(note);
2046                                }
2047                                return;
2048                            }
2049                            Variant
2050                            | Field
2051                            | Closure
2052                            | AssocTy
2053                            | AssocConst
2054                            | AssocFn
2055                            | Fn
2056                            | Macro(_)
2057                            | Const
2058                            | ConstParam
2059                            | ExternCrate
2060                            | Use
2061                            | LifetimeParam
2062                            | Ctor(_, _)
2063                            | AnonConst
2064                            | InlineConst => {
2065                                let note = assoc_item_not_allowed(res);
2066                                if let Some(span) = sp {
2067                                    diag.span_label(span, note);
2068                                } else {
2069                                    diag.note(note);
2070                                }
2071                                return;
2072                            }
2073                            Trait
2074                            | TyAlias
2075                            | ForeignTy
2076                            | OpaqueTy
2077                            | TraitAlias
2078                            | TyParam
2079                            | Static { .. } => "associated item",
2080                            Impl { .. } | GlobalAsm | SyntheticCoroutineBody => {
2081                                unreachable!("not a path")
2082                            }
2083                        }
2084                    } else {
2085                        "associated item"
2086                    };
2087                    let name = res.name(tcx);
2088                    let note = format!(
2089                        "the {res} `{name}` has no {disamb_res} named `{unresolved}`",
2090                        res = res.descr(),
2091                        disamb_res = disambiguator.map_or(path_description, |d| d.descr()),
2092                    );
2093                    if let Some(span) = sp {
2094                        diag.span_label(span, note);
2095                    } else {
2096                        diag.note(note);
2097                    }
2098
2099                    continue;
2100                }
2101                let note = match failure {
2102                    ResolutionFailure::NotResolved { .. } => unreachable!("handled above"),
2103                    ResolutionFailure::WrongNamespace { res, expected_ns } => {
2104                        suggest_disambiguator(
2105                            res,
2106                            diag,
2107                            path_str,
2108                            link_range.clone(),
2109                            sp,
2110                            &diag_info,
2111                        );
2112
2113                        if let Some(disambiguator) = disambiguator
2114                            && !matches!(disambiguator, Disambiguator::Namespace(..))
2115                        {
2116                            format!(
2117                                "this link resolves to {}, which is not {} {}",
2118                                item(res),
2119                                disambiguator.article(),
2120                                disambiguator.descr()
2121                            )
2122                        } else {
2123                            format!(
2124                                "this link resolves to {}, which is not in the {} namespace",
2125                                item(res),
2126                                expected_ns.descr()
2127                            )
2128                        }
2129                    }
2130                };
2131                if let Some(span) = sp {
2132                    diag.span_label(span, note);
2133                } else {
2134                    diag.note(note);
2135                }
2136            }
2137        },
2138    );
2139}
2140
2141fn report_multiple_anchors(cx: &DocContext<'_>, diag_info: DiagnosticInfo<'_>) {
2142    let msg = format!("`{}` contains multiple anchors", diag_info.ori_link);
2143    anchor_failure(cx, diag_info, msg, 1)
2144}
2145
2146fn report_anchor_conflict(cx: &DocContext<'_>, diag_info: DiagnosticInfo<'_>, def_id: DefId) {
2147    let (link, kind) = (diag_info.ori_link, Res::from_def_id(cx.tcx, def_id).descr());
2148    let msg = format!("`{link}` contains an anchor, but links to {kind}s are already anchored");
2149    anchor_failure(cx, diag_info, msg, 0)
2150}
2151
2152/// Report an anchor failure.
2153fn anchor_failure(
2154    cx: &DocContext<'_>,
2155    diag_info: DiagnosticInfo<'_>,
2156    msg: String,
2157    anchor_idx: usize,
2158) {
2159    report_diagnostic(cx.tcx, BROKEN_INTRA_DOC_LINKS, msg, &diag_info, |diag, sp, _link_range| {
2160        if let Some(mut sp) = sp {
2161            if let Some((fragment_offset, _)) =
2162                diag_info.ori_link.char_indices().filter(|(_, x)| *x == '#').nth(anchor_idx)
2163            {
2164                sp = sp.with_lo(sp.lo() + BytePos(fragment_offset as _));
2165            }
2166            diag.span_label(sp, "invalid anchor");
2167        }
2168    });
2169}
2170
2171/// Report an error in the link disambiguator.
2172fn disambiguator_error(
2173    cx: &DocContext<'_>,
2174    mut diag_info: DiagnosticInfo<'_>,
2175    disambiguator_range: MarkdownLinkRange,
2176    msg: impl Into<DiagMessage> + Display,
2177) {
2178    diag_info.link_range = disambiguator_range;
2179    report_diagnostic(cx.tcx, BROKEN_INTRA_DOC_LINKS, msg, &diag_info, |diag, _sp, _link_range| {
2180        let msg = format!(
2181            "see {}/rustdoc/write-documentation/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators",
2182            crate::DOC_RUST_LANG_ORG_VERSION
2183        );
2184        diag.note(msg);
2185    });
2186}
2187
2188fn report_malformed_generics(
2189    cx: &DocContext<'_>,
2190    diag_info: DiagnosticInfo<'_>,
2191    err: MalformedGenerics,
2192    path_str: &str,
2193) {
2194    report_diagnostic(
2195        cx.tcx,
2196        BROKEN_INTRA_DOC_LINKS,
2197        format!("unresolved link to `{path_str}`"),
2198        &diag_info,
2199        |diag, sp, _link_range| {
2200            let note = match err {
2201                MalformedGenerics::UnbalancedAngleBrackets => "unbalanced angle brackets",
2202                MalformedGenerics::MissingType => "missing type for generic parameters",
2203                MalformedGenerics::HasFullyQualifiedSyntax => {
2204                    diag.note(
2205                        "see https://github.com/rust-lang/rust/issues/74563 for more information",
2206                    );
2207                    "fully-qualified syntax is unsupported"
2208                }
2209                MalformedGenerics::InvalidPathSeparator => "has invalid path separator",
2210                MalformedGenerics::TooManyAngleBrackets => "too many angle brackets",
2211                MalformedGenerics::EmptyAngleBrackets => "empty angle brackets",
2212            };
2213            if let Some(span) = sp {
2214                diag.span_label(span, note);
2215            } else {
2216                diag.note(note);
2217            }
2218        },
2219    );
2220}
2221
2222/// Report an ambiguity error, where there were multiple possible resolutions.
2223///
2224/// If all `candidates` have the same kind, it's not possible to disambiguate so in this case,
2225/// the function won't emit an error and will return `false`. Otherwise, it'll emit the error and
2226/// return `true`.
2227fn ambiguity_error(
2228    cx: &DocContext<'_>,
2229    diag_info: &DiagnosticInfo<'_>,
2230    path_str: &str,
2231    candidates: &[(Res, Option<DefId>)],
2232    emit_error: bool,
2233) -> bool {
2234    let mut descrs = FxHashSet::default();
2235    let kinds = candidates
2236        .iter()
2237        .map(
2238            |(res, def_id)| {
2239                if let Some(def_id) = def_id { Res::from_def_id(cx.tcx, *def_id) } else { *res }
2240            },
2241        )
2242        .filter(|res| descrs.insert(res.descr()))
2243        .collect::<Vec<_>>();
2244    if descrs.len() == 1 {
2245        // There is no way for users to disambiguate at this point, so better return the first
2246        // candidate and not show a warning.
2247        return false;
2248    } else if !emit_error {
2249        return true;
2250    }
2251
2252    let mut msg = format!("`{path_str}` is ");
2253    match kinds.as_slice() {
2254        [res1, res2] => {
2255            msg += &format!(
2256                "both {} {} and {} {}",
2257                res1.article(),
2258                res1.descr(),
2259                res2.article(),
2260                res2.descr()
2261            );
2262        }
2263        _ => {
2264            let mut kinds = kinds.iter().peekable();
2265            while let Some(res) = kinds.next() {
2266                if kinds.peek().is_some() {
2267                    msg += &format!("{} {}, ", res.article(), res.descr());
2268                } else {
2269                    msg += &format!("and {} {}", res.article(), res.descr());
2270                }
2271            }
2272        }
2273    }
2274
2275    report_diagnostic(cx.tcx, BROKEN_INTRA_DOC_LINKS, msg, diag_info, |diag, sp, link_range| {
2276        if let Some(sp) = sp {
2277            diag.span_label(sp, "ambiguous link");
2278        } else {
2279            diag.note("ambiguous link");
2280        }
2281
2282        for res in kinds {
2283            suggest_disambiguator(res, diag, path_str, link_range.clone(), sp, diag_info);
2284        }
2285    });
2286    true
2287}
2288
2289/// In case of an ambiguity or mismatched disambiguator, suggest the correct
2290/// disambiguator.
2291fn suggest_disambiguator(
2292    res: Res,
2293    diag: &mut Diag<'_, ()>,
2294    path_str: &str,
2295    link_range: MarkdownLinkRange,
2296    sp: Option<rustc_span::Span>,
2297    diag_info: &DiagnosticInfo<'_>,
2298) {
2299    let suggestion = res.disambiguator_suggestion();
2300    let help = format!("to link to the {}, {}", res.descr(), suggestion.descr());
2301
2302    let ori_link = match link_range {
2303        MarkdownLinkRange::Destination(range) => Some(&diag_info.dox[range]),
2304        MarkdownLinkRange::WholeLink(_) => None,
2305    };
2306
2307    if let (Some(sp), Some(ori_link)) = (sp, ori_link) {
2308        let mut spans = suggestion.as_help_span(ori_link, sp);
2309        if spans.len() > 1 {
2310            diag.multipart_suggestion(help, spans, Applicability::MaybeIncorrect);
2311        } else {
2312            let (sp, suggestion_text) = spans.pop().unwrap();
2313            diag.span_suggestion_verbose(sp, help, suggestion_text, Applicability::MaybeIncorrect);
2314        }
2315    } else {
2316        diag.help(format!("{help}: {}", suggestion.as_help(path_str)));
2317    }
2318}
2319
2320/// Report a link from a public item to a private one.
2321fn privacy_error(cx: &DocContext<'_>, diag_info: &DiagnosticInfo<'_>, path_str: &str) {
2322    let sym;
2323    let item_name = match diag_info.item.name {
2324        Some(name) => {
2325            sym = name;
2326            sym.as_str()
2327        }
2328        None => "<unknown>",
2329    };
2330    let msg = format!("public documentation for `{item_name}` links to private item `{path_str}`");
2331
2332    report_diagnostic(cx.tcx, PRIVATE_INTRA_DOC_LINKS, msg, diag_info, |diag, sp, _link_range| {
2333        if let Some(sp) = sp {
2334            diag.span_label(sp, "this item is private");
2335        }
2336
2337        let note_msg = if cx.render_options.document_private {
2338            "this link resolves only because you passed `--document-private-items`, but will break without"
2339        } else {
2340            "this link will resolve properly if you pass `--document-private-items`"
2341        };
2342        diag.note(note_msg);
2343    });
2344}
2345
2346/// Resolve a primitive type or value.
2347fn resolve_primitive(path_str: &str, ns: Namespace) -> Option<Res> {
2348    if ns != TypeNS {
2349        return None;
2350    }
2351    use PrimitiveType::*;
2352    let prim = match path_str {
2353        "isize" => Isize,
2354        "i8" => I8,
2355        "i16" => I16,
2356        "i32" => I32,
2357        "i64" => I64,
2358        "i128" => I128,
2359        "usize" => Usize,
2360        "u8" => U8,
2361        "u16" => U16,
2362        "u32" => U32,
2363        "u64" => U64,
2364        "u128" => U128,
2365        "f16" => F16,
2366        "f32" => F32,
2367        "f64" => F64,
2368        "f128" => F128,
2369        "char" => Char,
2370        "bool" | "true" | "false" => Bool,
2371        "str" | "&str" => Str,
2372        // See #80181 for why these don't have symbols associated.
2373        "slice" => Slice,
2374        "array" => Array,
2375        "tuple" => Tuple,
2376        "unit" => Unit,
2377        "pointer" | "*const" | "*mut" => RawPointer,
2378        "reference" | "&" | "&mut" => Reference,
2379        "fn" => Fn,
2380        "never" | "!" => Never,
2381        _ => return None,
2382    };
2383    debug!("resolved primitives {prim:?}");
2384    Some(Res::Primitive(prim))
2385}