[rustdoc] Merge <code> tags into one whenever possible

[GuillaumeGomez]

Fixes #62867.
Fixes #83997.

When we have multiple <code> tags following each others, we never tried merging them into one, especially when a <code> is inside a <a>. This PR merges them into one <code>, making the generated HTML shorter. And it has the nice side-effect of also making it look nicer.

Before:

After:

You can test it here.

r? @notriddle

[hkBst]

The "A <Stream a> stuff." does not seem to get rid of extra spacing yet... for me on firefox if that matters.

• <Stream> vs <Stream a>
• <code>&lt;<a href="[struct.Foo.html](view-source:https://rustdoc.crud.net/imperio/merge-code-tags/foo/struct.Foo.html)" title="struct foo::Foo">Stream</a>&gt;</code> vs
• <code>&lt;</code><a href="[struct.Foo.html](view-source:https://rustdoc.crud.net/imperio/merge-code-tags/foo/struct.Foo.html)" title="struct foo::Foo"><code>Stream</code> a</a><code>&gt;</code>

The < is still in its own code block...

[notriddle]

I'm not convinced that this is a good solution?

Other markdown implementations don't merge consecutive code blocks, the resulting source is noisy with ` marks, and you can already fix this with <code> tags like in this example from #88343:

Additionally, the return value of this function is [`fmt::Result`] which is a

type alias of <code>[Result]<(), [std::fmt::Error]></code>. Formatting implementations

The alternative, [`Result`]`<(), `[`std::fmt::Error`]`>`, has a bunch more formatting characters inside the intended text, which seems worse than the HTML-based solution.

[GuillaumeGomez]

The "A <Stream a> stuff." does not seem to get rid of extra spacing yet... for me on firefox if that matters.

* `<Stream>` vs `<``Stream` a`>`

* `<code>&lt;<a href="[struct.Foo.html](view-source:https://rustdoc.crud.net/imperio/merge-code-tags/foo/struct.Foo.html)" title="struct foo::Foo">Stream</a>&gt;</code>` vs

* `<code>&lt;</code><a href="[struct.Foo.html](view-source:https://rustdoc.crud.net/imperio/merge-code-tags/foo/struct.Foo.html)" title="struct foo::Foo"><code>Stream</code> a</a><code>&gt;</code>`

The < is still in its own code block...

Obviously yes. A whitespace is a character on its own and should not be merged if not part of a code. And in the case you displayed, it's even worse: it's a non-<code> in a <a>. We can improve this situation with CSS but it'll be part of a follow-up.

I'm not convinced that this is a good solution?

Other markdown implementations don't merge consecutive code blocks, the resulting source is noisy with ` marks, and you can already fix this with <code> tags like in this example from #88343:

Additionally, the return value of this function is [`fmt::Result`] which is a
type alias of **<code>[Result]<(), [std::fmt::Error]></code>**. Formatting implementations

The alternative, [`Result`]`<(), `[`std::fmt::Error`]`>`, has a bunch more formatting characters inside the intended text, which seems worse than the HTML-based solution.

It's a case common enough when intra-doc links are used and people are generally not aware that you can simply use HTML with markdown. I agree that it's less good than using <code>, but it's worth noting that even in the std, there are cases like that.

An alternative would be writing a rustdoc lint. I tend to prefer the current approach as it's invisible to the user though.

[notriddle]

We've merged the clippy lint.

Since it solves the same problem, this PR isn't a complete solution, and it's not clear if any complete solution is coming, I propose we close this PR and its linked issues as not-planed.

@rfcbot poll we should recommend HTML <code> tags to anyone who runs into this

[rfcbot]

Team member @notriddle has asked teams: T-rustdoc, for consensus on:

we should recommend HTML <code> tags to anyone who runs into this

• @GuillaumeGomez
• @Manishearth
• @Nemo157
• @aDotInTheVoid
• @camelid
• @fmease
• @jsha
• @notriddle

[GuillaumeGomez]

Let's close it, no need to wait for the FCP to be over.