提交 e66a8c26 编写于 作者: B bors

Auto merge of #87285 - GuillaumeGomez:intra-doc-span, r=estebank

Improve intra doc errors display

#87169

`@jyn514` This is what I had in mind to avoid having duplicated backticks. I also gave a try to simply updating the span for the suggestion/help messages but I think this current one is better because less "noisy". Anyway, that allows you to see the result. ;)
......@@ -19,7 +19,7 @@
use rustc_session::lint::Lint;
use rustc_span::hygiene::{MacroKind, SyntaxContext};
use rustc_span::symbol::{sym, Ident, Symbol};
use rustc_span::DUMMY_SP;
use rustc_span::{BytePos, DUMMY_SP};
use smallvec::{smallvec, SmallVec};
use pulldown_cmark::LinkType;
......@@ -1193,7 +1193,7 @@ fn resolve_link(
let report_mismatch = |specified: Disambiguator, resolved: Disambiguator| {
// The resolved item did not match the disambiguator; give a better error than 'not found'
let msg = format!("incompatible link kind for `{}`", path_str);
let callback = |diag: &mut DiagnosticBuilder<'_>, sp| {
let callback = |diag: &mut DiagnosticBuilder<'_>, sp: Option<rustc_span::Span>| {
let note = format!(
"this link resolved to {} {}, which is not {} {}",
resolved.article(),
......@@ -1201,8 +1201,12 @@ fn resolve_link(
specified.article(),
specified.descr()
);
diag.note(&note);
suggest_disambiguator(resolved, diag, path_str, dox, sp, &ori_link.range);
if let Some(sp) = sp {
diag.span_label(sp, &note);
} else {
diag.note(&note);
}
suggest_disambiguator(resolved, diag, path_str, &ori_link.link, sp);
};
report_diagnostic(self.cx.tcx, BROKEN_INTRA_DOC_LINKS, &msg, &diag_info, callback);
};
......@@ -1699,6 +1703,51 @@ fn as_help(&self, path_str: &str) -> String {
Self::RemoveDisambiguator => path_str.into(),
}
}
fn as_help_span(
&self,
path_str: &str,
ori_link: &str,
sp: rustc_span::Span,
) -> Vec<(rustc_span::Span, String)> {
let inner_sp = match ori_link.find('(') {
Some(index) => sp.with_hi(sp.lo() + BytePos(index as _)),
None => sp,
};
let inner_sp = match ori_link.find('!') {
Some(index) => inner_sp.with_hi(inner_sp.lo() + BytePos(index as _)),
None => inner_sp,
};
let inner_sp = match ori_link.find('@') {
Some(index) => inner_sp.with_lo(inner_sp.lo() + BytePos(index as u32 + 1)),
None => inner_sp,
};
match self {
Self::Prefix(prefix) => {
// FIXME: if this is an implied shortcut link, it's bad style to suggest `@`
let mut sugg = vec![(sp.with_hi(inner_sp.lo()), format!("{}@", prefix))];
if sp.hi() != inner_sp.hi() {
sugg.push((inner_sp.shrink_to_hi().with_hi(sp.hi()), String::new()));
}
sugg
}
Self::Function => {
let mut sugg = vec![(inner_sp.shrink_to_hi().with_hi(sp.hi()), "()".to_string())];
if sp.lo() != inner_sp.lo() {
sugg.push((inner_sp.shrink_to_lo().with_lo(sp.lo()), String::new()));
}
sugg
}
Self::Macro => {
let mut sugg = vec![(inner_sp.shrink_to_hi(), "!".to_string())];
if sp.lo() != inner_sp.lo() {
sugg.push((inner_sp.shrink_to_lo().with_lo(sp.lo()), String::new()));
}
sugg
}
Self::RemoveDisambiguator => return vec![(sp, path_str.into())],
}
}
}
/// Reports a diagnostic for an intra-doc link.
......@@ -1732,7 +1781,16 @@ fn report_diagnostic(
tcx.struct_span_lint_hir(lint, hir_id, sp, |lint| {
let mut diag = lint.build(msg);
let span = super::source_span_for_markdown_range(tcx, dox, link_range, &item.attrs);
let span =
super::source_span_for_markdown_range(tcx, dox, link_range, &item.attrs).map(|sp| {
if dox.bytes().nth(link_range.start) == Some(b'`')
&& dox.bytes().nth(link_range.end - 1) == Some(b'`')
{
sp.with_lo(sp.lo() + BytePos(1)).with_hi(sp.hi() - BytePos(1))
} else {
sp
}
});
if let Some(sp) = span {
diag.set_span(sp);
......@@ -1938,9 +1996,8 @@ fn split(path: &str) -> Option<(&str, &str)> {
disambiguator,
diag,
path_str,
diag_info.dox,
diag_info.ori_link,
sp,
&diag_info.link_range,
)
}
......@@ -2007,7 +2064,7 @@ fn anchor_failure(cx: &DocContext<'_>, diag_info: DiagnosticInfo<'_>, failure: A
if let Some((fragment_offset, _)) =
diag_info.ori_link.char_indices().filter(|(_, x)| *x == '#').nth(anchor_idx)
{
sp = sp.with_lo(sp.lo() + rustc_span::BytePos(fragment_offset as _));
sp = sp.with_lo(sp.lo() + BytePos(fragment_offset as _));
}
diag.span_label(sp, "invalid anchor");
}
......@@ -2075,14 +2132,7 @@ fn ambiguity_error(
for res in candidates {
let disambiguator = Disambiguator::from_res(res);
suggest_disambiguator(
disambiguator,
diag,
path_str,
diag_info.dox,
sp,
&diag_info.link_range,
);
suggest_disambiguator(disambiguator, diag, path_str, diag_info.ori_link, sp);
}
});
}
......@@ -2093,21 +2143,20 @@ fn suggest_disambiguator(
disambiguator: Disambiguator,
diag: &mut DiagnosticBuilder<'_>,
path_str: &str,
dox: &str,
ori_link: &str,
sp: Option<rustc_span::Span>,
link_range: &Range<usize>,
) {
let suggestion = disambiguator.suggestion();
let help = format!("to link to the {}, {}", disambiguator.descr(), suggestion.descr());
if let Some(sp) = sp {
let msg = if dox.bytes().nth(link_range.start) == Some(b'`') {
format!("`{}`", suggestion.as_help(path_str))
let mut spans = suggestion.as_help_span(path_str, ori_link, sp);
if spans.len() > 1 {
diag.multipart_suggestion(&help, spans, Applicability::MaybeIncorrect);
} else {
suggestion.as_help(path_str)
};
diag.span_suggestion(sp, &help, msg, Applicability::MaybeIncorrect);
let (sp, suggestion_text) = spans.pop().unwrap();
diag.span_suggestion_verbose(sp, &help, suggestion_text, Applicability::MaybeIncorrect);
}
} else {
diag.help(&format!("{}: {}", help, suggestion.as_help(path_str)));
}
......
error: unresolved link to `S::fmt`
--> $DIR/assoc-item-not-in-scope.rs:4:14
--> $DIR/assoc-item-not-in-scope.rs:4:15
|
LL | /// Link to [`S::fmt`]
| ^^^^^^^^ the struct `S` has no field or associated item named `fmt`
| ^^^^^^ the struct `S` has no field or associated item named `fmt`
|
note: the lint level is defined here
--> $DIR/assoc-item-not-in-scope.rs:1:9
......
......@@ -12,26 +12,26 @@ LL | #![deny(rustdoc::broken_intra_doc_links)]
help: to link to the module, prefix with `mod@`
|
LL | /// [mod@true]
| ^^^^^^^^
| ^^^^
help: to link to the builtin type, prefix with `prim@`
|
LL | /// [prim@true]
| ^^^^^^^^^
| ^^^^^
error: `ambiguous` is both a struct and a function
--> $DIR/ambiguity.rs:27:6
--> $DIR/ambiguity.rs:27:7
|
LL | /// [`ambiguous`] is ambiguous.
| ^^^^^^^^^^^ ambiguous link
| ^^^^^^^^^ ambiguous link
|
help: to link to the struct, prefix with `struct@`
|
LL | /// [`struct@ambiguous`] is ambiguous.
| ^^^^^^^^^^^^^^^^^^
| ^^^^^^^
help: to link to the function, add parentheses
|
LL | /// [`ambiguous()`] is ambiguous.
| ^^^^^^^^^^^^^
| ^^
error: `ambiguous` is both a struct and a function
--> $DIR/ambiguity.rs:29:6
......@@ -42,30 +42,30 @@ LL | /// [ambiguous] is ambiguous.
help: to link to the struct, prefix with `struct@`
|
LL | /// [struct@ambiguous] is ambiguous.
| ^^^^^^^^^^^^^^^^
| ^^^^^^^
help: to link to the function, add parentheses
|
LL | /// [ambiguous()] is ambiguous.
| ^^^^^^^^^^^
| ^^
error: `multi_conflict` is a struct, a function, and a macro
--> $DIR/ambiguity.rs:31:6
--> $DIR/ambiguity.rs:31:7
|
LL | /// [`multi_conflict`] is a three-way conflict.
| ^^^^^^^^^^^^^^^^ ambiguous link
| ^^^^^^^^^^^^^^ ambiguous link
|
help: to link to the struct, prefix with `struct@`
|
LL | /// [`struct@multi_conflict`] is a three-way conflict.
| ^^^^^^^^^^^^^^^^^^^^^^^
| ^^^^^^^
help: to link to the function, add parentheses
|
LL | /// [`multi_conflict()`] is a three-way conflict.
| ^^^^^^^^^^^^^^^^^^
| ^^
help: to link to the macro, add an exclamation mark
|
LL | /// [`multi_conflict!`] is a three-way conflict.
| ^^^^^^^^^^^^^^^^^
| ^
error: `type_and_value` is both a module and a constant
--> $DIR/ambiguity.rs:33:16
......@@ -76,26 +76,26 @@ LL | /// Ambiguous [type_and_value].
help: to link to the module, prefix with `mod@`
|
LL | /// Ambiguous [mod@type_and_value].
| ^^^^^^^^^^^^^^^^^^
| ^^^^
help: to link to the constant, prefix with `const@`
|
LL | /// Ambiguous [const@type_and_value].
| ^^^^^^^^^^^^^^^^^^^^
| ^^^^^^
error: `foo::bar` is both an enum and a function
--> $DIR/ambiguity.rs:35:42
--> $DIR/ambiguity.rs:35:43
|
LL | /// Ambiguous non-implied shortcut link [`foo::bar`].
| ^^^^^^^^^^ ambiguous link
| ^^^^^^^^ ambiguous link
|
help: to link to the enum, prefix with `enum@`
|
LL | /// Ambiguous non-implied shortcut link [`enum@foo::bar`].
| ^^^^^^^^^^^^^^^
| ^^^^^
help: to link to the function, add parentheses
|
LL | /// Ambiguous non-implied shortcut link [`foo::bar()`].
| ^^^^^^^^^^^^
| ^^
error: aborting due to 6 previous errors
#![deny(rustdoc::broken_intra_doc_links)]
//~^ NOTE lint level is defined
pub enum S {}
fn S() {}
#[macro_export]
macro_rules! m {
() => {};
}
......@@ -41,6 +43,12 @@ trait T {}
//~| NOTE this link resolved
//~| HELP add an exclamation mark
/// Link to [m()]
//~^ ERROR unresolved link to `m`
//~| NOTE this link resolves to the macro `m`
//~| HELP add an exclamation mark
/// and to [m!()]
/// Link to [const@s]
//~^ ERROR incompatible link kind for `s`
//~| NOTE this link resolved
......
error: incompatible link kind for `S`
--> $DIR/disambiguator-mismatch.rs:14:14
--> $DIR/disambiguator-mismatch.rs:16:14
|
LL | /// Link to [struct@S]
| ^^^^^^^^ help: to link to the enum, prefix with `enum@`: `enum@S`
| ^^^^^^^^ this link resolved to an enum, which is not a struct
|
note: the lint level is defined here
--> $DIR/disambiguator-mismatch.rs:1:9
|
LL | #![deny(rustdoc::broken_intra_doc_links)]
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
= note: this link resolved to an enum, which is not a struct
help: to link to the enum, prefix with `enum@`
|
LL | /// Link to [enum@S]
| ^^^^^
error: incompatible link kind for `S`
--> $DIR/disambiguator-mismatch.rs:19:14
--> $DIR/disambiguator-mismatch.rs:21:14
|
LL | /// Link to [mod@S]
| ^^^^^ help: to link to the enum, prefix with `enum@`: `enum@S`
| ^^^^^ this link resolved to an enum, which is not a module
|
help: to link to the enum, prefix with `enum@`
|
= note: this link resolved to an enum, which is not a module
LL | /// Link to [enum@S]
| ^^^^^
error: incompatible link kind for `S`
--> $DIR/disambiguator-mismatch.rs:24:14
--> $DIR/disambiguator-mismatch.rs:26:14
|
LL | /// Link to [union@S]
| ^^^^^^^ help: to link to the enum, prefix with `enum@`: `enum@S`
| ^^^^^^^ this link resolved to an enum, which is not a union
|
= note: this link resolved to an enum, which is not a union
help: to link to the enum, prefix with `enum@`
|
LL | /// Link to [enum@S]
| ^^^^^
error: incompatible link kind for `S`
--> $DIR/disambiguator-mismatch.rs:29:14
--> $DIR/disambiguator-mismatch.rs:31:14
|
LL | /// Link to [trait@S]
| ^^^^^^^ help: to link to the enum, prefix with `enum@`: `enum@S`
| ^^^^^^^ this link resolved to an enum, which is not a trait
|
help: to link to the enum, prefix with `enum@`
|
= note: this link resolved to an enum, which is not a trait
LL | /// Link to [enum@S]
| ^^^^^
error: incompatible link kind for `T`
--> $DIR/disambiguator-mismatch.rs:34:14
--> $DIR/disambiguator-mismatch.rs:36:14
|
LL | /// Link to [struct@T]
| ^^^^^^^^ help: to link to the trait, prefix with `trait@`: `trait@T`
| ^^^^^^^^ this link resolved to a trait, which is not a struct
|
= note: this link resolved to a trait, which is not a struct
help: to link to the trait, prefix with `trait@`
|
LL | /// Link to [trait@T]
| ^^^^^^
error: incompatible link kind for `m`
--> $DIR/disambiguator-mismatch.rs:39:14
--> $DIR/disambiguator-mismatch.rs:41:14
|
LL | /// Link to [derive@m]
| ^^^^^^^^ help: to link to the macro, add an exclamation mark: `m!`
| ^^^^^^^^ this link resolved to a macro, which is not a derive macro
|
help: to link to the macro, add an exclamation mark
|
= note: this link resolved to a macro, which is not a derive macro
LL | /// Link to [m!]
| --^
error: unresolved link to `m`
--> $DIR/disambiguator-mismatch.rs:46:14
|
LL | /// Link to [m()]
| ^^^ this link resolves to the macro `m`, which is not in the value namespace
|
help: to link to the macro, add an exclamation mark
|
LL | /// Link to [m!()]
| ^
error: incompatible link kind for `s`
--> $DIR/disambiguator-mismatch.rs:44:14
--> $DIR/disambiguator-mismatch.rs:52:14
|
LL | /// Link to [const@s]
| ^^^^^^^ help: to link to the static, prefix with `static@`: `static@s`
| ^^^^^^^ this link resolved to a static, which is not a constant
|
= note: this link resolved to a static, which is not a constant
help: to link to the static, prefix with `static@`
|
LL | /// Link to [static@s]
| ^^^^^^^
error: incompatible link kind for `c`
--> $DIR/disambiguator-mismatch.rs:49:14
--> $DIR/disambiguator-mismatch.rs:57:14
|
LL | /// Link to [static@c]
| ^^^^^^^^ help: to link to the constant, prefix with `const@`: `const@c`
| ^^^^^^^^ this link resolved to a constant, which is not a static
|
help: to link to the constant, prefix with `const@`
|
= note: this link resolved to a constant, which is not a static
LL | /// Link to [const@c]
| ^^^^^^
error: incompatible link kind for `c`
--> $DIR/disambiguator-mismatch.rs:54:14
--> $DIR/disambiguator-mismatch.rs:62:14
|
LL | /// Link to [fn@c]
| ^^^^ help: to link to the constant, prefix with `const@`: `const@c`
| ^^^^ this link resolved to a constant, which is not a function
|
= note: this link resolved to a constant, which is not a function
help: to link to the constant, prefix with `const@`
|
LL | /// Link to [const@c]
| ^^^^^^
error: incompatible link kind for `c`
--> $DIR/disambiguator-mismatch.rs:59:14
--> $DIR/disambiguator-mismatch.rs:67:14
|
LL | /// Link to [c()]
| ^^^ help: to link to the constant, prefix with `const@`: `const@c`
| ^^^ this link resolved to a constant, which is not a function
|
help: to link to the constant, prefix with `const@`
|
= note: this link resolved to a constant, which is not a function
LL | /// Link to [const@c]
| ^^^^^^--
error: incompatible link kind for `f`
--> $DIR/disambiguator-mismatch.rs:64:14
--> $DIR/disambiguator-mismatch.rs:72:14
|
LL | /// Link to [const@f]
| ^^^^^^^ help: to link to the function, add parentheses: `f()`
| ^^^^^^^ this link resolved to a function, which is not a constant
|
help: to link to the function, add parentheses
|
= note: this link resolved to a function, which is not a constant
LL | /// Link to [f()]
| --^^
error: aborting due to 11 previous errors
error: aborting due to 12 previous errors
......@@ -92,37 +92,45 @@ error: unresolved link to `Vec::into_iter`
--> $DIR/errors.rs:63:6
|
LL | /// [type@Vec::into_iter]
| ^^^^^^^^^^^^^^^^^^^
| |
| this link resolves to the associated function `into_iter`, which is not in the type namespace
| help: to link to the associated function, add parentheses: `Vec::into_iter()`
| ^^^^^^^^^^^^^^^^^^^ this link resolves to the associated function `into_iter`, which is not in the type namespace
|
help: to link to the associated function, add parentheses
|
LL | /// [Vec::into_iter()]
| -- ^^
error: unresolved link to `S`
--> $DIR/errors.rs:68:6
|
LL | /// [S!]
| ^^
| |
| this link resolves to the struct `S`, which is not in the macro namespace
| help: to link to the struct, prefix with `struct@`: `struct@S`
| ^^ this link resolves to the struct `S`, which is not in the macro namespace
|
help: to link to the struct, prefix with `struct@`
|
LL | /// [struct@S]
| ^^^^^^^--
error: unresolved link to `S::h`
--> $DIR/errors.rs:78:6
|
LL | /// [type@S::h]
| ^^^^^^^^^
| |
| this link resolves to the associated function `h`, which is not in the type namespace
| help: to link to the associated function, add parentheses: `S::h()`
| ^^^^^^^^^ this link resolves to the associated function `h`, which is not in the type namespace
|
help: to link to the associated function, add parentheses
|
LL | /// [S::h()]
| -- ^^
error: unresolved link to `T::g`
--> $DIR/errors.rs:86:6
|
LL | /// [type@T::g]
| ^^^^^^^^^
| |
| this link resolves to the associated function `g`, which is not in the type namespace
| help: to link to the associated function, add parentheses: `T::g()`
| ^^^^^^^^^ this link resolves to the associated function `g`, which is not in the type namespace
|
help: to link to the associated function, add parentheses
|
LL | /// [T::g()]
| -- ^^
error: unresolved link to `T::h`
--> $DIR/errors.rs:91:6
......@@ -134,10 +142,12 @@ error: unresolved link to `m`
--> $DIR/errors.rs:98:6
|
LL | /// [m()]
| ^^^
| |
| this link resolves to the macro `m`, which is not in the value namespace
| help: to link to the macro, add an exclamation mark: `m!`
| ^^^ this link resolves to the macro `m`, which is not in the value namespace
|
help: to link to the macro, add an exclamation mark
|
LL | /// [m!()]
| ^
error: aborting due to 20 previous errors
error: incompatible link kind for `Foo::bar`
--> $DIR/field-ice.rs:5:6
--> $DIR/field-ice.rs:5:7
|
LL | /// [`Foo::bar()`]
| ^^^^^^^^^^^^ help: to link to the field, remove the disambiguator: ``Foo::bar``
| ^^^^^^^^^^ this link resolved to a field, which is not a function
|
note: the lint level is defined here
--> $DIR/field-ice.rs:1:9
|
LL | #![deny(rustdoc::broken_intra_doc_links)]
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
= note: this link resolved to a field, which is not a function
help: to link to the field, remove the disambiguator
|
LL | /// [`Foo::bar`]
| ^^^^^^^^
error: aborting due to previous error
......@@ -2,14 +2,17 @@ error: incompatible link kind for `u8::MIN`
--> $DIR/incompatible-primitive-disambiguator.rs:2:6
|
LL | //! [static@u8::MIN]
| ^^^^^^^^^^^^^^ help: to link to the associated constant, prefix with `const@`: `const@u8::MIN`
| ^^^^^^^^^^^^^^ this link resolved to an associated constant, which is not a static
|
note: the lint level is defined here
--> $DIR/incompatible-primitive-disambiguator.rs:1:9
|
LL | #![deny(rustdoc::broken_intra_doc_links)]
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
= note: this link resolved to an associated constant, which is not a static
help: to link to the associated constant, prefix with `const@`
|
LL | //! [const@u8::MIN]
| ^^^^^^
error: aborting due to previous error
......@@ -12,11 +12,11 @@ LL | #![deny(rustdoc::broken_intra_doc_links)]
help: to link to the module, prefix with `mod@`
|
LL | /// [mod@char]
| ^^^^^^^^
| ^^^^
help: to link to the builtin type, prefix with `prim@`
|
LL | /// [prim@char]
| ^^^^^^^^^
| ^^^^^
error: `char` is both a module and a builtin type
--> $DIR/prim-conflict.rs:10:6
......@@ -27,27 +27,33 @@ LL | /// [type@char]
help: to link to the module, prefix with `mod@`
|
LL | /// [mod@char]
| ^^^^^^^^
| ^^^^
help: to link to the builtin type, prefix with `prim@`
|
LL | /// [prim@char]
| ^^^^^^^^^
| ^^^^^
error: incompatible link kind for `char`
--> $DIR/prim-conflict.rs:19:6
|
LL | /// [struct@char]
| ^^^^^^^^^^^ help: to link to the module, prefix with `mod@`: `mod@char`
| ^^^^^^^^^^^ this link resolved to a module, which is not a struct
|
= note: this link resolved to a module, which is not a struct
help: to link to the module, prefix with `mod@`
|
LL | /// [mod@char]
| ^^^^
error: incompatible link kind for `char`
--> $DIR/prim-conflict.rs:26:10
|
LL | //! [struct@char]
| ^^^^^^^^^^^ help: to link to the builtin type, prefix with `prim@`: `prim@char`
| ^^^^^^^^^^^ this link resolved to a builtin type, which is not a struct
|
help: to link to the builtin type, prefix with `prim@`
|
= note: this link resolved to a builtin type, which is not a struct
LL | //! [prim@char]
| ^^^^^
error: aborting due to 4 previous errors
warning: public documentation for `public_item` links to private item `PrivateType`
--> $DIR/issue-74134.rs:19:10
--> $DIR/issue-74134.rs:19:11
|
LL | /// [`PrivateType`]
| ^^^^^^^^^^^^^ this item is private
| ^^^^^^^^^^^ this item is private
|
= note: `#[warn(rustdoc::private_intra_doc_links)]` on by default
= note: this link resolves only because you passed `--document-private-items`, but will break without
......
warning: public documentation for `public_item` links to private item `PrivateType`
--> $DIR/issue-74134.rs:19:10
--> $DIR/issue-74134.rs:19:11
|
LL | /// [`PrivateType`]
| ^^^^^^^^^^^^^ this item is private
| ^^^^^^^^^^^ this item is private
|
= note: `#[warn(rustdoc::private_intra_doc_links)]` on by default
= note: this link will resolve properly if you pass `--document-private-items`
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册