rust-lang / rust-lang/cargo

Intra-doc links not resolved in workspace with proc-macro

Open
#11,628 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

C-bug Command-doc E-hard S-needs-design
Dominant language
Rust
Stars
15.5k
Forks
3k
Avg merge
23h 30m
Merged PRs (30d)
51

Description

Problem

There are doc links that sometimes refuse to work, I found a reproducible way of witnessing it.

Steps

Make sure rust-analyzer is not running for reproducibility. clone doc-bug, run cargo clean and cargo doc --open at the root of the workspace. Click on the awint_macros crate in the "Crates" list and scroll all the way to the bottom of the lib docs (I can't reduce further because it causes the problem to go away). There is a broken doc link with the literal text [awint_macro_internals::awint_macro_inlawi] towards the bottom.

Then, go to the source code awint/awint_macros/src/lib.rs and make some dummy change like adding a "// hello" comment somewhere. Run just cargo doc and refresh, now the doc link is no longer broken.

Possible Solution(s)

No response

Notes

It probably has to do with cargo-doc getting confused when there are multiple transitive dependencies and multiple reexports of items. Recompiling sometimes breaks or fixes it strangely.

Version
cargo 1.69.0-nightly (985d561f0 2023-01-20)
release: 1.69.0-nightly
commit-hash: 985d561f0bb9b76ec043a2b12511790ec7a2b954
commit-date: 2023-01-20
host: x86_64-pc-windows-msvc
libgit2: 1.5.1 (sys:0.16.1 vendored)
libcurl: 7.86.0-DEV (sys:0.4.59+curl-7.86.0 vendored ssl:Schannel)
os: Windows 10.0.19045 (Windows 10 Home) [64-bit]

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

Reproduce the failure with the linked doc-bug workspace by running cargo clean and cargo doc --open, then compare the generated awint_macros documentation before and after the dummy change in awint/awint_macros/src/lib.rs. Start by tracing how cargo doc resolves intra-doc links across transitive dependencies and reexports. Done means the awint_macro_internals link resolves consistently after a clean documentation build.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.