Skip to content

Improve diagnostics when intra-doc-resolution fails #75305

Closed
@jyn514

Description

@jyn514

Similar to but not the same as #74207. Right now rustdoc reports the same error for all the following cases:

/// [<invalid syntax>]
/// [path::to::nonexistent::module]
/// [f::A]
/// [S::A]
/// [S::fmt]
pub fn f() {}
#[derive(Debug)]
pub struct S;
warning: unresolved link to `path::to::nonexistent::module`
 --> /dev/stdin:2:6
  |
2 | /// [path::to::nonexistent::module]
  |      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ unresolved link
  |
  = note: `#[warn(broken_intra_doc_links)]` on by default
  = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`

However we can give much more helpful errors:

1 | /// [<invalid syntax>]
  |     ^^^^^^^^^^^^^^^^^^ not valid syntax for an intra-doc link
2 | /// [path::to::nonexistent::module]
  |      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ use of undeclared type or module `path` 
3 | /// [f::A]
  |     ^^^^^^ functions cannot have associated items
4 | /// [S::A]
  |     ^^^^^^ `S` does not have an associated item `A` in scope. help: try importing a trait that defines that item
5 | /// [S::fmt]
  |     ^^^^^^ `S` does not have an associated item `fmt` in scope. help: S implements `std::fmt::Debug`, try importing it.

Most of these do not require special help from rustc_resolve (that would just let rustdoc duplicate less code).

Metadata

Metadata

Assignees

Labels

A-diagnosticsArea: Messages for errors, warnings, and lintsA-intra-doc-linksArea: Intra-doc links, the ability to link to items in docs by nameC-enhancementCategory: An issue proposing an enhancement or a PR with one.D-terseDiagnostics: An error or lint that doesn't give enough information about the problem at hand.T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions