rustdoc: parse item and reexport markdown separate

[notriddle]

This change is a pre-requisite for LaTeX support, because the markdown parser doesn't support enabling and disabling extensions in the middle of a document, and there's no way to add that. This means string concatenating a document that has LaTeX Math disabled with a document that has it enabled can't be done.

As part of this change, a bug related to intra-doc links is 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

[obi1kenobi]

I'm curious, when might this Vec have more than one element?

It might be useful to include an example in the doc comment, for ease of use.

View changes since the review

[notriddle]

Good call. I've added an example and some description to the docs.

The full markdown docstring of this item. Empty if there is no documentation at all,
vec![Doc { text: "" }] if there is some documentation but it is empty (EG #[doc = ""]),
and multiple items if a reexport and the original both have docstrings.

/// Reexport docs
pub use Thing1 as Thing2;

/// Original docs
pub struct Thing1;

{
    "name": "Thing2",
    "docs": [
        { "text": "Reexport docs", "links": [] },
        { "text": "Original docs", "links": [] },
    ],
    ...
}

[obi1kenobi]

Ah interesting! Nice, thank you.

Is any particular order of elements guaranteed? That's the only remaining thing I'd consider adding.

[notriddle]

Is any particular order of elements guaranteed?

It's guaranteed to be in the same order that the HTML frontend shows it. It always puts the reexport first and the original second, but the reexports section of the rustdoc book doesn't seem to promise that.

Even if it did, I'm not sure how it would help, because there's no way to distinguish case 1 from case 2:

// case 1: doc comment on reexport

struct Original1;

/// foo
pub use Original1 as Reexport1;

// case 2: doc comment on original

/// foo
struct Original2;

pub use Original2 as Reexport2;

Both of these generate "docs":[{"text":"foo","links":[]}]. To fix that, we'd need to add an explicit marker, at which point we might as well explicitly mark the two-comment case.

[obi1kenobi]

Good to know, thank you. It might be good to include a "No particular order is guaranteed" line in the doc comment, to ward off questions and/or Hyrum's Law. I'm not sure if the HTML guarantee is explicitly intended or accidental / implementation-defined, and it might not be worth including either way.

[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.