rust-lang / rust-lang/rust

rustdoc does not detect broken markdown due to missing links (except for links without a space)

Open
#141,227 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-intra-doc-links A-lints C-enhancement T-rustdoc
Dominant language
Rust
Stars
119k
Forks
16.1k
PR merge metrics
PR metrics pending

Description

I changed [allocated object] to [allocation] in docs, and strangely that triggered an error. Turns out the docs had a broken link, which you can see live at https://doc.rust-lang.org/1.87.0/std/primitive.pointer.html#method.split_at_mut_unchecked (note the "[allocated object]") -- but rustdoc somehow wouldn't complain unless the link text has no spaces? Something very strange is going on here.

See https://github.com/rust-lang/rust/pull/141224 for context. The error emitted after the change is below:

  error: unresolved link to `allocation`
      --> library/core/src/ptr/mut_ptr.rs:1851:54
       |
  1851 |     /// `mid` must be [in-bounds] of the underlying [allocation].
       |                                                      ^^^^^^^^^^ no item named `allocation` in scope
       |
       = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
       = note: `-D rustdoc::broken-intra-doc-links` implied by `-D warnings`
       = help: to override `-D warnings` add `#[allow(rustdoc::broken_intra_doc_links)]`

Possibly related: https://github.com/rust-lang/rust/issues/130126

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the broken link example in library/core/src/ptr/mut_ptr.rs:1851 and compare rustdoc behavior for link text with and without spaces. Read PR 141224 for context, then review related issue 130126. Done means the reported broken-link case is consistently diagnosed with regression coverage.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.