rustdoc: parse item and reexport markdown separate

[notriddle]

View all comments

Change the way Rustdoc behaves when a re-export and its original item both have doc comments.

In other words, code like this:

/// original
struct Foo;

/// re-export
pub use Foo as Bar;

In the current version of Rustdoc, the rendering is equivalent to:

/// re-export
/// original
pub use Bar;

Because there's no blank line between the comments, you get "re-export original" as a single paragraph.

The new version, introduced by this pull request, renders two paragraphs. It actually runs the Markdown parser separately for both items, so link refdefs, footnotes, and, in the future, syntax features are scoped separately.

This change is a pre-requisite for LaTeX support, because it introduces the notion of syntax features into Rustdoc's Markdown. It lets you turn tex_math_dollars support on and off.

As part of this change, a bug related to intra-doc links is also fixed. This shows up when the reexport and the item both have intra-doc links with the same visible path, but where they resolve to different items. The bug is demonstrated in
tests/rustdoc-html/reexport/link-with-same-name-but-different-destination.rs.

The other test case changes demonstrate that this is, technically, a breaking change. When I ran a Crater test for docs that rely on this behavior, though, it seemed most authors weren't relying on it.

[rustbot]

These commits modify tests/rustdoc-json.
rustdoc-json is a public (but unstable) interface.

Please ensure that if you've changed the output:

• It's intentional.
• The FORMAT_VERSION in src/librustdoc-json-types is bumped if necessary.

cc @obi1kenobi

rustdoc-json-types is a public (although nightly-only) API. If possible, consider changing src/librustdoc/json/conversions.rs; otherwise, make sure you bump the FORMAT_VERSION constant.

cc @CraftSpider, @Enselic, @obi1kenobi

[rustbot]

r? @GuillaumeGomez

rustbot has assigned @GuillaumeGomez.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

• Owners of files modified in this PR: rustdoc
• rustdoc expanded to 8 candidates
• Random selection from GuillaumeGomez, lolbinarycat

[rustbot]

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.