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<</code><a href="../../std/cell/struct.RefCell.html"><code>RefCell<T></code></a><code>></code>
I think better would be
/// <code>Arc<[RefCell<T>][RefCell]></code>
which presumably is rendered in one block as
<code>Arc<<a href="../../std/cell/struct.RefCell.html">RefCell<T></a>></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.
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 theArcthread safety section containsHere, between
Arc<andRefCell, 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 asI think better would be
/// <code>Arc<[RefCell<T>][RefCell]></code>which presumably is rendered in one block as
(I'm not sure if the link to
RefCellgets atitleattribute 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.