Unify error reporting for intra-doc links
- Give a suggestion even if there is no span available - Give a more accurate description of the change than 'use the disambiguator' - Write much less code
This commit is contained in:
Joshua Nelson
parent
18e7a1b799
commit
56d3f3963c
@ -898,20 +898,8 @@ fn fold_item(&mut self, mut item: Item) -> Option<Item> {
|
||||
specified.article(),
|
||||
specified.descr()
|
||||
);
|
||||
let suggestion = resolved.display_for(path_str);
|
||||
let help_msg =
|
||||
format!("to link to the {}, use its disambiguator", resolved.descr());
|
||||
diag.note(¬e);
|
||||
if let Some(sp) = sp {
|
||||
diag.span_suggestion(
|
||||
sp,
|
||||
&help_msg,
|
||||
suggestion,
|
||||
Applicability::MaybeIncorrect,
|
||||
);
|
||||
} else {
|
||||
diag.help(&format!("{}: {}", help_msg, suggestion));
|
||||
}
|
||||
suggest_disambiguator(resolved, diag, path_str, &dox, sp, &link_range);
|
||||
});
|
||||
};
|
||||
if let Res::PrimTy(_) = res {
|
||||
@ -1047,17 +1035,31 @@ fn from_str(link: &str) -> Result<(Self, &str), ()> {
|
||||
}
|
||||
}
|
||||
|
||||
fn display_for(self, path_str: &str) -> String {
|
||||
fn from_res(res: Res) -> Self {
|
||||
match res {
|
||||
Res::Def(kind, _) => Disambiguator::Kind(kind),
|
||||
Res::PrimTy(_) => Disambiguator::Primitive,
|
||||
_ => Disambiguator::Namespace(res.ns().expect("can't call `from_res` on Res::err")),
|
||||
}
|
||||
}
|
||||
|
||||
/// Return (description of the change, suggestion)
|
||||
fn display_for(self, path_str: &str) -> (&'static str, String) {
|
||||
const PREFIX: &str = "prefix with the item kind";
|
||||
const FUNCTION: &str = "add parentheses";
|
||||
const MACRO: &str = "add an exclamation mark";
|
||||
|
||||
let kind = match self {
|
||||
Disambiguator::Primitive => return format!("prim@{}", path_str),
|
||||
Disambiguator::Primitive => return (PREFIX, format!("prim@{}", path_str)),
|
||||
Disambiguator::Kind(kind) => kind,
|
||||
Disambiguator::Namespace(_) => panic!("display_for cannot be used on namespaces"),
|
||||
};
|
||||
if kind == DefKind::Macro(MacroKind::Bang) {
|
||||
return format!("{}!", path_str);
|
||||
return (MACRO, format!("{}!", path_str));
|
||||
} else if kind == DefKind::Fn || kind == DefKind::AssocFn {
|
||||
return format!("{}()", path_str);
|
||||
return (FUNCTION, format!("{}()", path_str));
|
||||
}
|
||||
|
||||
let prefix = match kind {
|
||||
DefKind::Struct => "struct",
|
||||
DefKind::Enum => "enum",
|
||||
@ -1079,7 +1081,9 @@ fn display_for(self, path_str: &str) -> String {
|
||||
Namespace::MacroNS => "macro",
|
||||
},
|
||||
};
|
||||
format!("{}@{}", prefix, path_str)
|
||||
|
||||
// FIXME: if this is an implied shortcut link, it's bad style to suggest `@`
|
||||
(PREFIX, format!("{}@{}", prefix, path_str))
|
||||
}
|
||||
|
||||
fn ns(self) -> Namespace {
|
||||
@ -1276,54 +1280,41 @@ fn ambiguity_error(
|
||||
report_diagnostic(cx, &msg, item, dox, link_range.clone(), |diag, sp| {
|
||||
if let Some(sp) = sp {
|
||||
diag.span_label(sp, "ambiguous link");
|
||||
} else {
|
||||
diag.note("ambiguous link");
|
||||
}
|
||||
|
||||
let link_range = link_range.expect("must have a link range if we have a span");
|
||||
|
||||
for (res, ns) in candidates {
|
||||
let (action, mut suggestion) = match res {
|
||||
Res::Def(DefKind::AssocFn | DefKind::Fn, _) => {
|
||||
("add parentheses", format!("{}()", path_str))
|
||||
}
|
||||
Res::Def(DefKind::Macro(MacroKind::Bang), _) => {
|
||||
("add an exclamation mark", format!("{}!", path_str))
|
||||
}
|
||||
_ => {
|
||||
let type_ = match (res, ns) {
|
||||
(Res::PrimTy(_), _) => "prim",
|
||||
(Res::Def(DefKind::Const, _), _) => "const",
|
||||
(Res::Def(DefKind::Static, _), _) => "static",
|
||||
(Res::Def(DefKind::Struct, _), _) => "struct",
|
||||
(Res::Def(DefKind::Enum, _), _) => "enum",
|
||||
(Res::Def(DefKind::Union, _), _) => "union",
|
||||
(Res::Def(DefKind::Trait, _), _) => "trait",
|
||||
(Res::Def(DefKind::Mod, _), _) => "module",
|
||||
(_, TypeNS) => "type",
|
||||
(_, ValueNS) => "value",
|
||||
(Res::Def(DefKind::Macro(MacroKind::Derive), _), MacroNS) => "derive",
|
||||
(_, MacroNS) => "macro",
|
||||
};
|
||||
|
||||
// FIXME: if this is an implied shortcut link, it's bad style to suggest `@`
|
||||
("prefix with the item type", format!("{}@{}", type_, path_str))
|
||||
}
|
||||
};
|
||||
|
||||
if dox.bytes().nth(link_range.start) == Some(b'`') {
|
||||
suggestion = format!("`{}`", suggestion);
|
||||
}
|
||||
|
||||
// FIXME: Create a version of this suggestion for when we don't have the span.
|
||||
diag.span_suggestion(
|
||||
sp,
|
||||
&format!("to link to the {}, {}", res.descr(), action),
|
||||
suggestion,
|
||||
Applicability::MaybeIncorrect,
|
||||
);
|
||||
}
|
||||
for (res, _ns) in candidates {
|
||||
let disambiguator = Disambiguator::from_res(res);
|
||||
suggest_disambiguator(disambiguator, diag, path_str, dox, sp, &link_range);
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
fn suggest_disambiguator(
|
||||
disambiguator: Disambiguator,
|
||||
diag: &mut DiagnosticBuilder<'_>,
|
||||
path_str: &str,
|
||||
dox: &str,
|
||||
sp: Option<rustc_span::Span>,
|
||||
link_range: &Option<Range<usize>>,
|
||||
) {
|
||||
let (action, mut suggestion) = disambiguator.display_for(path_str);
|
||||
let help = format!("to link to the {}, {}", disambiguator.descr(), action);
|
||||
|
||||
if let Some(sp) = sp {
|
||||
let link_range = link_range.as_ref().expect("must have a link range if we have a span");
|
||||
if dox.bytes().nth(link_range.start) == Some(b'`') {
|
||||
suggestion = format!("`{}`", suggestion);
|
||||
}
|
||||
|
||||
// FIXME: Create a version of this suggestion for when we don't have the span.
|
||||
diag.span_suggestion(sp, &help, suggestion, Applicability::MaybeIncorrect);
|
||||
} else {
|
||||
diag.help(&format!("{}: {}", help, suggestion));
|
||||
}
|
||||
}
|
||||
|
||||
fn privacy_error(
|
||||
cx: &DocContext<'_>,
|
||||
item: &Item,
|
||||
|
||||
@ -18,13 +18,13 @@
|
||||
|
||||
/// [struct@char]
|
||||
//~^ ERROR incompatible link
|
||||
//~| HELP use its disambiguator
|
||||
//~| HELP prefix with the item kind
|
||||
//~| NOTE resolved to a module
|
||||
pub mod char {}
|
||||
|
||||
pub mod inner {
|
||||
//! [struct@char]
|
||||
//~^ ERROR incompatible link
|
||||
//~| HELP use its disambiguator
|
||||
//~| HELP prefix with the item kind
|
||||
//~| NOTE resolved to a builtin type
|
||||
}
|
||||
|
||||
@ -9,11 +9,11 @@ note: the lint level is defined here
|
||||
|
|
||||
LL | #![deny(broken_intra_doc_links)]
|
||||
| ^^^^^^^^^^^^^^^^^^^^^^
|
||||
help: to link to the module, prefix with the item type
|
||||
help: to link to the module, prefix with the item kind
|
||||
|
|
||||
LL | /// [module@char]
|
||||
| ^^^^^^^^^^^
|
||||
help: to link to the builtin type, prefix with the item type
|
||||
LL | /// [mod@char]
|
||||
| ^^^^^^^^
|
||||
help: to link to the builtin type, prefix with the item kind
|
||||
|
|
||||
LL | /// [prim@char]
|
||||
| ^^^^^^^^^
|
||||
@ -24,11 +24,11 @@ error: `char` is both a module and a builtin type
|
||||
LL | /// [type@char]
|
||||
| ^^^^^^^^^ ambiguous link
|
||||
|
|
||||
help: to link to the module, prefix with the item type
|
||||
help: to link to the module, prefix with the item kind
|
||||
|
|
||||
LL | /// [module@char]
|
||||
| ^^^^^^^^^^^
|
||||
help: to link to the builtin type, prefix with the item type
|
||||
LL | /// [mod@char]
|
||||
| ^^^^^^^^
|
||||
help: to link to the builtin type, prefix with the item kind
|
||||
|
|
||||
LL | /// [prim@char]
|
||||
| ^^^^^^^^^
|
||||
@ -37,17 +37,25 @@ error: incompatible link kind for `char`
|
||||
--> $DIR/intra-link-prim-conflict.rs:19:6
|
||||
|
|
||||
LL | /// [struct@char]
|
||||
| ^^^^^^^^^^^ help: to link to the module, use its disambiguator: `mod@char`
|
||||
| ^^^^^^^^^^^
|
||||
|
|
||||
= note: this link resolved to a module, which is not a struct
|
||||
help: to link to the module, prefix with the item kind
|
||||
|
|
||||
LL | /// [mod@char]
|
||||
| ^^^^^^^^
|
||||
|
||||
error: incompatible link kind for `char`
|
||||
--> $DIR/intra-link-prim-conflict.rs:26:10
|
||||
|
|
||||
LL | //! [struct@char]
|
||||
| ^^^^^^^^^^^ help: to link to the builtin type, use its disambiguator: `prim@char`
|
||||
| ^^^^^^^^^^^
|
||||
|
|
||||
= note: this link resolved to a builtin type, which is not a struct
|
||||
help: to link to the builtin type, prefix with the item kind
|
||||
|
|
||||
LL | //! [prim@char]
|
||||
| ^^^^^^^^^
|
||||
|
||||
error: aborting due to 4 previous errors
|
||||
|
||||
|
||||
@ -9,7 +9,7 @@ note: the lint level is defined here
|
||||
|
|
||||
LL | #![deny(broken_intra_doc_links)]
|
||||
| ^^^^^^^^^^^^^^^^^^^^^^
|
||||
help: to link to the struct, prefix with the item type
|
||||
help: to link to the struct, prefix with the item kind
|
||||
|
|
||||
LL | /// [`struct@ambiguous`] is ambiguous.
|
||||
| ^^^^^^^^^^^^^^^^^^
|
||||
@ -24,7 +24,7 @@ error: `ambiguous` is both a struct and a function
|
||||
LL | /// [ambiguous] is ambiguous.
|
||||
| ^^^^^^^^^ ambiguous link
|
||||
|
|
||||
help: to link to the struct, prefix with the item type
|
||||
help: to link to the struct, prefix with the item kind
|
||||
|
|
||||
LL | /// [struct@ambiguous] is ambiguous.
|
||||
| ^^^^^^^^^^^^^^^^
|
||||
@ -39,7 +39,7 @@ error: `multi_conflict` is a struct, a function, and a macro
|
||||
LL | /// [`multi_conflict`] is a three-way conflict.
|
||||
| ^^^^^^^^^^^^^^^^ ambiguous link
|
||||
|
|
||||
help: to link to the struct, prefix with the item type
|
||||
help: to link to the struct, prefix with the item kind
|
||||
|
|
||||
LL | /// [`struct@multi_conflict`] is a three-way conflict.
|
||||
| ^^^^^^^^^^^^^^^^^^^^^^^
|
||||
@ -58,11 +58,11 @@ error: `type_and_value` is both a module and a constant
|
||||
LL | /// Ambiguous [type_and_value].
|
||||
| ^^^^^^^^^^^^^^ ambiguous link
|
||||
|
|
||||
help: to link to the module, prefix with the item type
|
||||
help: to link to the module, prefix with the item kind
|
||||
|
|
||||
LL | /// Ambiguous [module@type_and_value].
|
||||
| ^^^^^^^^^^^^^^^^^^^^^
|
||||
help: to link to the constant, prefix with the item type
|
||||
LL | /// Ambiguous [mod@type_and_value].
|
||||
| ^^^^^^^^^^^^^^^^^^
|
||||
help: to link to the constant, prefix with the item kind
|
||||
|
|
||||
LL | /// Ambiguous [const@type_and_value].
|
||||
| ^^^^^^^^^^^^^^^^^^^^
|
||||
@ -73,7 +73,7 @@ error: `foo::bar` is both an enum and a function
|
||||
LL | /// Ambiguous non-implied shortcut link [`foo::bar`].
|
||||
| ^^^^^^^^^^ ambiguous link
|
||||
|
|
||||
help: to link to the enum, prefix with the item type
|
||||
help: to link to the enum, prefix with the item kind
|
||||
|
|
||||
LL | /// Ambiguous non-implied shortcut link [`enum@foo::bar`].
|
||||
| ^^^^^^^^^^^^^^^
|
||||
|
||||
@ -14,55 +14,55 @@ trait T {}
|
||||
/// Link to [struct@S]
|
||||
//~^ ERROR incompatible link kind for `S`
|
||||
//~| NOTE this link resolved
|
||||
//~| HELP use its disambiguator
|
||||
//~| HELP prefix with the item kind
|
||||
|
||||
/// Link to [mod@S]
|
||||
//~^ ERROR incompatible link kind for `S`
|
||||
//~| NOTE this link resolved
|
||||
//~| HELP use its disambiguator
|
||||
//~| HELP prefix with the item kind
|
||||
|
||||
/// Link to [union@S]
|
||||
//~^ ERROR incompatible link kind for `S`
|
||||
//~| NOTE this link resolved
|
||||
//~| HELP use its disambiguator
|
||||
//~| HELP prefix with the item kind
|
||||
|
||||
/// Link to [trait@S]
|
||||
//~^ ERROR incompatible link kind for `S`
|
||||
//~| NOTE this link resolved
|
||||
//~| HELP use its disambiguator
|
||||
//~| HELP prefix with the item kind
|
||||
|
||||
/// Link to [struct@T]
|
||||
//~^ ERROR incompatible link kind for `T`
|
||||
//~| NOTE this link resolved
|
||||
//~| HELP use its disambiguator
|
||||
//~| HELP prefix with the item kind
|
||||
|
||||
/// Link to [derive@m]
|
||||
//~^ ERROR incompatible link kind for `m`
|
||||
//~| NOTE this link resolved
|
||||
//~| HELP use its disambiguator
|
||||
//~| HELP add an exclamation mark
|
||||
|
||||
/// Link to [const@s]
|
||||
//~^ ERROR incompatible link kind for `s`
|
||||
//~| NOTE this link resolved
|
||||
//~| HELP use its disambiguator
|
||||
//~| HELP prefix with the item kind
|
||||
|
||||
/// Link to [static@c]
|
||||
//~^ ERROR incompatible link kind for `c`
|
||||
//~| NOTE this link resolved
|
||||
//~| HELP use its disambiguator
|
||||
//~| HELP prefix with the item kind
|
||||
|
||||
/// Link to [fn@c]
|
||||
//~^ ERROR incompatible link kind for `c`
|
||||
//~| NOTE this link resolved
|
||||
//~| HELP use its disambiguator
|
||||
//~| HELP prefix with the item kind
|
||||
|
||||
/// Link to [c()]
|
||||
//~^ ERROR incompatible link kind for `c`
|
||||
//~| NOTE this link resolved
|
||||
//~| HELP use its disambiguator
|
||||
//~| HELP prefix with the item kind
|
||||
|
||||
/// Link to [const@f]
|
||||
//~^ ERROR incompatible link kind for `f`
|
||||
//~| NOTE this link resolved
|
||||
//~| HELP use its disambiguator
|
||||
//~| HELP add parentheses
|
||||
pub fn f() {}
|
||||
|
||||
@ -2,7 +2,7 @@ error: incompatible link kind for `S`
|
||||
--> $DIR/intra-links-disambiguator-mismatch.rs:14:14
|
||||
|
|
||||
LL | /// Link to [struct@S]
|
||||
| ^^^^^^^^ help: to link to the enum, use its disambiguator: `enum@S`
|
||||
| ^^^^^^^^
|
||||
|
|
||||
note: the lint level is defined here
|
||||
--> $DIR/intra-links-disambiguator-mismatch.rs:1:9
|
||||
@ -10,44 +10,64 @@ note: the lint level is defined here
|
||||
LL | #![deny(broken_intra_doc_links)]
|
||||
| ^^^^^^^^^^^^^^^^^^^^^^
|
||||
= note: this link resolved to an enum, which is not a struct
|
||||
help: to link to the enum, prefix with the item kind
|
||||
|
|
||||
LL | /// Link to [enum@S]
|
||||
| ^^^^^^
|
||||
|
||||
error: incompatible link kind for `S`
|
||||
--> $DIR/intra-links-disambiguator-mismatch.rs:19:14
|
||||
|
|
||||
LL | /// Link to [mod@S]
|
||||
| ^^^^^ help: to link to the enum, use its disambiguator: `enum@S`
|
||||
| ^^^^^
|
||||
|
|
||||
= note: this link resolved to an enum, which is not a module
|
||||
help: to link to the enum, prefix with the item kind
|
||||
|
|
||||
LL | /// Link to [enum@S]
|
||||
| ^^^^^^
|
||||
|
||||
error: incompatible link kind for `S`
|
||||
--> $DIR/intra-links-disambiguator-mismatch.rs:24:14
|
||||
|
|
||||
LL | /// Link to [union@S]
|
||||
| ^^^^^^^ help: to link to the enum, use its disambiguator: `enum@S`
|
||||
| ^^^^^^^
|
||||
|
|
||||
= note: this link resolved to an enum, which is not a union
|
||||
help: to link to the enum, prefix with the item kind
|
||||
|
|
||||
LL | /// Link to [enum@S]
|
||||
| ^^^^^^
|
||||
|
||||
error: incompatible link kind for `S`
|
||||
--> $DIR/intra-links-disambiguator-mismatch.rs:29:14
|
||||
|
|
||||
LL | /// Link to [trait@S]
|
||||
| ^^^^^^^ help: to link to the enum, use its disambiguator: `enum@S`
|
||||
| ^^^^^^^
|
||||
|
|
||||
= note: this link resolved to an enum, which is not a trait
|
||||
help: to link to the enum, prefix with the item kind
|
||||
|
|
||||
LL | /// Link to [enum@S]
|
||||
| ^^^^^^
|
||||
|
||||
error: incompatible link kind for `T`
|
||||
--> $DIR/intra-links-disambiguator-mismatch.rs:34:14
|
||||
|
|
||||
LL | /// Link to [struct@T]
|
||||
| ^^^^^^^^ help: to link to the trait, use its disambiguator: `trait@T`
|
||||
| ^^^^^^^^
|
||||
|
|
||||
= note: this link resolved to a trait, which is not a struct
|
||||
help: to link to the trait, prefix with the item kind
|
||||
|
|
||||
LL | /// Link to [trait@T]
|
||||
| ^^^^^^^
|
||||
|
||||
error: incompatible link kind for `m`
|
||||
--> $DIR/intra-links-disambiguator-mismatch.rs:39:14
|
||||
|
|
||||
LL | /// Link to [derive@m]
|
||||
| ^^^^^^^^ help: to link to the macro, use its disambiguator: `m!`
|
||||
| ^^^^^^^^ help: to link to the macro, add an exclamation mark: `m!`
|
||||
|
|
||||
= note: this link resolved to a macro, which is not a derive macro
|
||||
|
||||
@ -55,39 +75,55 @@ error: incompatible link kind for `s`
|
||||
--> $DIR/intra-links-disambiguator-mismatch.rs:44:14
|
||||
|
|
||||
LL | /// Link to [const@s]
|
||||
| ^^^^^^^ help: to link to the static, use its disambiguator: `static@s`
|
||||
| ^^^^^^^
|
||||
|
|
||||
= note: this link resolved to a static, which is not a constant
|
||||
help: to link to the static, prefix with the item kind
|
||||
|
|
||||
LL | /// Link to [static@s]
|
||||
| ^^^^^^^^
|
||||
|
||||
error: incompatible link kind for `c`
|
||||
--> $DIR/intra-links-disambiguator-mismatch.rs:49:14
|
||||
|
|
||||
LL | /// Link to [static@c]
|
||||
| ^^^^^^^^ help: to link to the constant, use its disambiguator: `const@c`
|
||||
| ^^^^^^^^
|
||||
|
|
||||
= note: this link resolved to a constant, which is not a static
|
||||
help: to link to the constant, prefix with the item kind
|
||||
|
|
||||
LL | /// Link to [const@c]
|
||||
| ^^^^^^^
|
||||
|
||||
error: incompatible link kind for `c`
|
||||
--> $DIR/intra-links-disambiguator-mismatch.rs:54:14
|
||||
|
|
||||
LL | /// Link to [fn@c]
|
||||
| ^^^^ help: to link to the constant, use its disambiguator: `const@c`
|
||||
| ^^^^
|
||||
|
|
||||
= note: this link resolved to a constant, which is not a function
|
||||
help: to link to the constant, prefix with the item kind
|
||||
|
|
||||
LL | /// Link to [const@c]
|
||||
| ^^^^^^^
|
||||
|
||||
error: incompatible link kind for `c`
|
||||
--> $DIR/intra-links-disambiguator-mismatch.rs:59:14
|
||||
|
|
||||
LL | /// Link to [c()]
|
||||
| ^^^ help: to link to the constant, use its disambiguator: `const@c`
|
||||
| ^^^
|
||||
|
|
||||
= note: this link resolved to a constant, which is not a function
|
||||
help: to link to the constant, prefix with the item kind
|
||||
|
|
||||
LL | /// Link to [const@c]
|
||||
| ^^^^^^^
|
||||
|
||||
error: incompatible link kind for `f`
|
||||
--> $DIR/intra-links-disambiguator-mismatch.rs:64:14
|
||||
|
|
||||
LL | /// Link to [const@f]
|
||||
| ^^^^^^^ help: to link to the function, use its disambiguator: `f()`
|
||||
| ^^^^^^^ help: to link to the function, add parentheses: `f()`
|
||||
|
|
||||
= note: this link resolved to a function, which is not a constant
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user