rust-lang / rust-lang/rust

rustdoc: Footnotes don't work well when used on multiple doc comments that share page.

Open
#131,901 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-rustdoc-ui C-enhancement T-rustdoc T-rustdoc-frontend
Dominant language
Rust
Stars
119k
Forks
16.1k
PR merge metrics
PR metrics pending

Description

pub struct Foo;

impl Foo {
    /// Link 1 [^1]
    ///
    /// [^1]: Hiya
    pub fn l1(){}

    /// Link 2 [^2]
    ///
    /// [^2]: Biya
    pub fn l2() {}
}

Image

Not only is this ugly, but both footnotes use the same link/number, despite being seperate in the source code.

I think the right thing to do here is to show all footnotes for a page in one place (at the bottom). This may have some subtle interactions with when markdown content appears on multiple pages (eg summaries, trait methods), but I've not looked into the details yet.

Origionly inspired by this output:

Image

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 by reproducing the issue with the Foo example in rustdoc and compare the generated page with the linked docs.rs output. Trace how footnotes from multiple doc comments are rendered on one page, including summaries and trait methods. Done means footnotes remain distinct and are collected in one place at the bottom of the page without breaking content shown on multiple pages.

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
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.