Skip to content

rustdoc: Cleanup doc link extraction #108209

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Feb 18, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 27 additions & 13 deletions compiler/rustc_resolve/src/rustdoc.rs
Original file line number Diff line number Diff line change
@@ -1,11 +1,10 @@
use pulldown_cmark::{BrokenLink, Event, Options, Parser, Tag};
use pulldown_cmark::{BrokenLink, Event, LinkType, Options, Parser, Tag};
use rustc_ast as ast;
use rustc_ast::util::comments::beautify_doc_string;
use rustc_data_structures::fx::FxHashMap;
use rustc_span::def_id::DefId;
use rustc_span::symbol::{kw, Symbol};
use rustc_span::Span;
use std::cell::RefCell;
use std::{cmp, mem};

#[derive(Clone, Copy, PartialEq, Eq, Debug)]
Expand Down Expand Up @@ -348,22 +347,37 @@ fn preprocess_link(link: &str) -> String {
strip_generics_from_path(link).unwrap_or_else(|_| link.to_string())
}

/// Keep inline and reference links `[]`,
/// but skip autolinks `<>` which we never consider to be intra-doc links.
pub fn may_be_doc_link(link_type: LinkType) -> bool {
match link_type {
LinkType::Inline
| LinkType::Reference
| LinkType::ReferenceUnknown
| LinkType::Collapsed
| LinkType::CollapsedUnknown
| LinkType::Shortcut
| LinkType::ShortcutUnknown => true,
LinkType::Autolink | LinkType::Email => false,
}
}

/// Simplified version of `preprocessed_markdown_links` from rustdoc.
/// Must return at least the same links as it, but may add some more links on top of that.
pub(crate) fn attrs_to_preprocessed_links(attrs: &[ast::Attribute]) -> Vec<String> {
let (doc_fragments, _) = attrs_to_doc_fragments(attrs.iter().map(|attr| (attr, None)), true);
let doc = prepare_to_doc_link_resolution(&doc_fragments).into_values().next().unwrap();

let links = RefCell::new(Vec::new());
let mut callback = |link: BrokenLink<'_>| {
links.borrow_mut().push(preprocess_link(&link.reference));
None
};
for event in Parser::new_with_broken_link_callback(&doc, main_body_opts(), Some(&mut callback))
{
if let Event::Start(Tag::Link(_, dest, _)) = event {
links.borrow_mut().push(preprocess_link(&dest));
Parser::new_with_broken_link_callback(
&doc,
main_body_opts(),
Some(&mut |link: BrokenLink<'_>| Some((link.reference, "".into()))),
)
.filter_map(|event| match event {
Event::Start(Tag::Link(link_type, dest, _)) if may_be_doc_link(link_type) => {
Some(preprocess_link(&dest))
}
}
links.into_inner()
_ => None,
})
.collect()
}
61 changes: 18 additions & 43 deletions src/librustdoc/html/markdown.rs
Original file line number Diff line number Diff line change
Expand Up @@ -29,12 +29,12 @@ use rustc_data_structures::fx::FxHashMap;
use rustc_hir::def_id::DefId;
use rustc_middle::ty::TyCtxt;
pub(crate) use rustc_resolve::rustdoc::main_body_opts;
use rustc_resolve::rustdoc::may_be_doc_link;
use rustc_span::edition::Edition;
use rustc_span::{Span, Symbol};

use once_cell::sync::Lazy;
use std::borrow::Cow;
use std::cell::RefCell;
use std::collections::VecDeque;
use std::default::Default;
use std::fmt::Write;
Expand Down Expand Up @@ -1226,14 +1226,12 @@ pub(crate) struct MarkdownLink {

pub(crate) fn markdown_links<R>(
md: &str,
filter_map: impl Fn(MarkdownLink) -> Option<R>,
preprocess_link: impl Fn(MarkdownLink) -> Option<R>,
) -> Vec<R> {
if md.is_empty() {
return vec![];
}

let links = RefCell::new(vec![]);

// FIXME: remove this function once pulldown_cmark can provide spans for link definitions.
let locate = |s: &str, fallback: Range<usize>| unsafe {
let s_start = s.as_ptr();
Expand Down Expand Up @@ -1265,46 +1263,23 @@ pub(crate) fn markdown_links<R>(
}
};

let mut push = |link: BrokenLink<'_>| {
let span = span_for_link(&link.reference, link.span);
filter_map(MarkdownLink {
kind: LinkType::ShortcutUnknown,
link: link.reference.to_string(),
range: span,
})
.map(|link| links.borrow_mut().push(link));
None
};
let p = Parser::new_with_broken_link_callback(md, main_body_opts(), Some(&mut push))
.into_offset_iter();

// There's no need to thread an IdMap through to here because
// the IDs generated aren't going to be emitted anywhere.
let mut ids = IdMap::new();
let iter = Footnotes::new(HeadingLinks::new(p, None, &mut ids, HeadingOffset::H1));

for ev in iter {
if let Event::Start(Tag::Link(
// `<>` links cannot be intra-doc links so we skip them.
kind @ (LinkType::Inline
| LinkType::Reference
| LinkType::ReferenceUnknown
| LinkType::Collapsed
| LinkType::CollapsedUnknown
| LinkType::Shortcut
| LinkType::ShortcutUnknown),
dest,
_,
)) = ev.0
{
debug!("found link: {dest}");
let span = span_for_link(&dest, ev.1);
filter_map(MarkdownLink { kind, link: dest.into_string(), range: span })
.map(|link| links.borrow_mut().push(link));
Parser::new_with_broken_link_callback(
md,
main_body_opts(),
Some(&mut |link: BrokenLink<'_>| Some((link.reference, "".into()))),
)
.into_offset_iter()
.filter_map(|(event, span)| match event {
Event::Start(Tag::Link(link_type, dest, _)) if may_be_doc_link(link_type) => {
preprocess_link(MarkdownLink {
kind: link_type,
range: span_for_link(&dest, span),
link: dest.into_string(),
})
}
}

links.into_inner()
_ => None,
})
.collect()
}

#[derive(Debug)]
Expand Down
32 changes: 16 additions & 16 deletions tests/rustdoc-ui/intra-doc/unknown-disambiguator.stderr
Original file line number Diff line number Diff line change
Expand Up @@ -20,22 +20,6 @@ LL | //! Linking to [foo@banana] and [`bar@banana!()`].
|
= note: see https://doc.rust-lang.org/$CHANNEL/rustdoc/write-documentation/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators

error: unknown disambiguator `foo`
--> $DIR/unknown-disambiguator.rs:10:34
|
LL | //! And with weird backticks: [``foo@hello``] [foo`@`hello].
| ^^^
|
= note: see https://doc.rust-lang.org/$CHANNEL/rustdoc/write-documentation/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators

error: unknown disambiguator `foo`
--> $DIR/unknown-disambiguator.rs:10:48
|
LL | //! And with weird backticks: [``foo@hello``] [foo`@`hello].
| ^^^
|
= note: see https://doc.rust-lang.org/$CHANNEL/rustdoc/write-documentation/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators

error: unknown disambiguator ``
--> $DIR/unknown-disambiguator.rs:7:31
|
Expand All @@ -52,5 +36,21 @@ LL | //! And to [no disambiguator](@nectarine) and [another](@apricot!()).
|
= note: see https://doc.rust-lang.org/$CHANNEL/rustdoc/write-documentation/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators

error: unknown disambiguator `foo`
--> $DIR/unknown-disambiguator.rs:10:34
|
LL | //! And with weird backticks: [``foo@hello``] [foo`@`hello].
| ^^^
|
= note: see https://doc.rust-lang.org/$CHANNEL/rustdoc/write-documentation/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators

error: unknown disambiguator `foo`
--> $DIR/unknown-disambiguator.rs:10:48
|
LL | //! And with weird backticks: [``foo@hello``] [foo`@`hello].
| ^^^
|
= note: see https://doc.rust-lang.org/$CHANNEL/rustdoc/write-documentation/linking-to-items-by-name.html#namespaces-and-disambiguators for more info about disambiguators

error: aborting due to 6 previous errors