Documentation: inline code with links split into multiple blocks #83997
Comments
tspiteri
changed the title
|
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.
See #80733 (comment) which I think is a very good approach and we might be able to do with CSS only (cc @camelid). |
camelid
added
C-feature-request
camelid
added
C-enhancement
|
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? |
|
Okay, I opened another issue: #84043. I'm not going to close this one without hearing back from other people on what they think, but I added a warning to the top of this issue so someone doesn't put energy into a PR before it is decided what we want to do. EDIT: That issue is a duplicate of #62867, so I closed the new issue. |
Fix spacing of links in inline code. Similar to rust-lang#80733, but the focus is different. This PR eliminates all occurrences of pieced-together inline code blocks like [`Box`]`<`[`Option`]`<T>>` and replaces them with good-looking ones (using HTML-syntax), like <code>[Box]<[Option]\<T>></code>. As far as I can tell, I should’ve found all of these in the standard library (regex search with `` r"`\]`|`\[`" ``) \[except for in `core::convert` where I’ve noticed other things in the docs that I want to fix in a separate PR]. In particular, unlike rust-lang#80733, I’ve added almost no new instance of inline code that’s broken up into multiple links (or some link and some link-free part). I also added tooltips (the stuff in quotes for the markdown link listings) in places that caught my eye, but that’s by no means systematic, just opportunistic. [Box]: https://doc.rust-lang.org/std/boxed/struct.Box.html "Box" [`Box`]: https://doc.rust-lang.org/std/boxed/struct.Box.html "Box" [Option]: https://doc.rust-lang.org/std/option/enum.Option.html "Option" [`Option`]: https://doc.rust-lang.org/std/option/enum.Option.html "Option" Context: I got annoyed by repeatedly running into new misformatted inline code while reading the standard library docs. I know that once issue rust-lang#83997 (and/or related ones) are resolved, these changes become somewhat obsolete, but I fail to notice much progress on that end right now. r? `@jyn514`
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.The text was updated successfully, but these errors were encountered: