Documentation: inline code with links split into multiple blocks

[tspiteri]

EDIT(camelid): ⚠️ Please do not open a PR for this! It is still under discussion.

---

Right now in the standard library documentation, when a piece of inline code has part of it linked, the code is split into multiple <code> blocks, which renders poorly. For example the Arc thread safety section contains

Here, between Arc< and RefCell, and between <T> and >, there is extra spacing. This is because the doc comment contains

/// `Arc<`[`RefCell<T>`]`>`

which is rendered using three <code> blocks as

<code>Arc&lt;</code><a href="../../std/cell/struct.RefCell.html"><code>RefCell&lt;T&gt;</code></a><code>&gt;</code>

I think better would be

/// <code>Arc&lt;[RefCell&lt;T&gt;][RefCell]&gt;</code>

which presumably is rendered in one block as

<code>Arc&lt;<a href="../../std/cell/struct.RefCell.html">RefCell&lt;T&gt;</a>&gt;</code>

(I'm not sure if the link to RefCell gets a title attribute as well).

The downside is that now the doc comment markdown is a bit hairy with explicit <code>, < and > spread throughout.

Is this substitution considered an improvement? If so I can grep through the code, make some substitutions, and open a PR.

An alternative solution would be to change rustdoc itself to combine consecutive code blocks, some of which could be wrapped inside <a>/</a>, into a single block, though I do not have the know-how to open such a PR. I don't even know if there is some downside to this that I am missing, where <code> blocks are meant to be separate, maybe for some markdown compliance or something.

[jyn514]

Yes, I think this is a good change - one like it has already been accepted (#80720) and I need to merge the other, thanks for reminding me (#80733). I need to open an issue for rustdoc to do this automatically - I don't know if it's worth spending time to convert the whole standard library by hand in the meantime.

An alternative solution would be to change rustdoc itself to combine consecutive code blocks, some of which could be wrapped inside <a>/</a>, into a single block, though I do not have the know-how to open such a PR. I don't even know if there is some downside to this that I am missing, where <code> blocks are meant to be separate, maybe for some markdown compliance or something.

See #80733 (comment) which I think is a very good approach and we might be able to do with CSS only (cc @camelid).

[camelid]

I think we should open a separate issue for changing rustdoc's behavior so it does this automatically, and then close this one. What do you think?