Skip to content

rustdoc: detect docs that use re-export concat - #162169

Draft
notriddle wants to merge 4 commits into
rust-lang:mainfrom
notriddle:rustdoc/unportable-markdown-re-export-concat
Draft

rustdoc: detect docs that use re-export concat#162169
notriddle wants to merge 4 commits into
rust-lang:mainfrom
notriddle:rustdoc/unportable-markdown-re-export-concat

Conversation

@notriddle

@notriddle notriddle commented Sep 2, 2026

Copy link
Copy Markdown
Contributor

DO NOT MERGE WITHOUT SETTING THE DEFAULT BACK TO WARN

This is a prereq for implementing LaTeX math (tracking issue: #162365). Because I want to be able to enable it on a per-docblock basis, re-exports need to be parsed with a different set of markdown parsing extensions than the items they link to, which means we can't just concatenate the strings and parse like we do now.

This was pointed out, in a similar case, by rust-lang/rfcs#3958 (comment)

IMO, markdown that relies on rustdoc’s current behavior is hard to understand, because string concatenation on separate doc comments is stupid.

This lint is mostly added here to run a Crater, so that we can figure out if there are significant numbers of crates are relying on the current behavior.

  • If I find that the number of docs fixed by parsing re-exports separately outnumbers docs that are broken, I think we should just make the change and open PRs against the few crates that were broken.
  • If it turns out that docs are purposefully using this, then I want to ship this compatibility lint for about a year after making the change, just like when people’s docs were being rendered differently because of the pulldown-cmark upgrade.

This is a prereq for implementing LaTeX math. Because I want to be able
to enable it on a per-docblock basis, re-exports need to be parsed with
a different set of markdown parsing extensions than the items they link
to, which means we can't just concatenate the strings and parse.

In any case, markdown that does this would be hard to understand.
We should probably lint on it anyway.
@rustbot rustbot added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Sep 2, 2026
@rust-log-analyzer

This comment has been minimized.

@rustbot rustbot added the T-rustdoc-frontend Relevant to the rustdoc-frontend team, which will review and decide on the web UI/UX output. label Sep 2, 2026
@rust-log-analyzer

This comment has been minimized.

I want to catch false positives before running crater, but it seems
like all of these really are re-exports.
@notriddle
notriddle force-pushed the rustdoc/unportable-markdown-re-export-concat branch from d0bf5b3 to c9f28f6 Compare September 2, 2026 13:32
@rust-log-analyzer

This comment has been minimized.

@notriddle

Copy link
Copy Markdown
Contributor Author

@bors try

@craterbot run mode=rustdoc

@craterbot

Copy link
Copy Markdown
Collaborator

🚨 Error: missing start toolchain

🆘 If you have any trouble with Crater please ask in t-infra on Zulip
ℹ️ Crater is a tool to run experiments across parts of the Rust ecosystem. Learn more

@rust-bors

This comment has been minimized.

rust-bors Bot pushed a commit that referenced this pull request Sep 2, 2026
…rt-concat, r=<try>

rustdoc: detect docs that use re-export concat
@rust-bors

rust-bors Bot commented Sep 2, 2026

Copy link
Copy Markdown
Contributor

☀️ Try build successful (CI)
Build commit: da3f5c3 (da3f5c31e5535b3dc210067de660a45784ae1e9c)
Base parent: 824336a (824336ad4127ce295849937a24c08a4aeff6ada7)

@notriddle

Copy link
Copy Markdown
Contributor Author

@craterbot run mode=rustdoc

@craterbot

Copy link
Copy Markdown
Collaborator

👌 Experiment pr-162169 created and queued.
🤖 Automatically detected try build da3f5c3
🔍 You can check out the queue and this experiment's details.

ℹ️ Crater is a tool to run experiments across parts of the Rust ecosystem. Learn more

@craterbot craterbot added S-waiting-on-crater Status: Waiting on a crater run to be completed. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Sep 2, 2026
@craterbot

Copy link
Copy Markdown
Collaborator

🚧 Experiment pr-162169 is now running

ℹ️ Crater is a tool to run experiments across parts of the Rust ecosystem. Learn more

@craterbot

Copy link
Copy Markdown
Collaborator

🎉 Experiment pr-162169 is completed!
📊 1053 regressed and 1 fixed (1103137 total)
📊 5067 spurious results on the retry-regressed-list.txt, consider a retry1 if this is a significant amount.
📰 Open the summary report.

⚠️ If you notice any spurious failure please add them to the denylist!
ℹ️ Crater is a tool to run experiments across parts of the Rust ecosystem. Learn more

Footnotes

  1. re-run the experiment with crates=https://crater-reports.s3.amazonaws.com/pr-162169/retry-regressed-list.txt

@craterbot craterbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-crater Status: Waiting on a crater run to be completed. labels Sep 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. T-rustdoc-frontend Relevant to the rustdoc-frontend team, which will review and decide on the web UI/UX output.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants