Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Rollup merge of rust-lang#80733 - steffahn:prettify_pin_links, r=jyn514
Improve links in inline code in `core::pin`. ## Context So I recently opened rust-lang#80720. That PR uses HTML-based `<code>foo</code>` syntax in place of `` `foo` `` for some inline code. It looks like usage of `<code>` tags in doc comments is without precedent in the standard library, but the HTML-based syntax has an important advantage: You can write something like ``` <code>[Box]<[Option]\<T>></code> ``` which becomes: <code>[Box]<[Option]\<T>></code>, whereas with ordinary backtick syntax, you cannot create links for a substring of an inline code block. ## Problem I recalled (from my own experience) that a way to partially work around this limitation is to do something like ``` [`Box`]`<`[`Option`]`<T>>` ``` which looks like this: [`Box`]`<`[`Option`]`<T>>` _(admitted, it looks even worse on GitHub than in `rustdoc`’s CSS)_. [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" [Pin]: https://doc.rust-lang.org/std/pin/struct.Pin.html "Pin" [&mut]: https://doc.rust-lang.org/std/primitive.reference.html "mutable reference" So I searched the standard library and found that e.g. the [std::pin](https://doc.rust-lang.org/std/pin/index.html) module documentation uses this hack/workaround quite a bit, with types like <code>[Pin]<[Box]\<T>></code> or <code>[Pin]<[&mut] T>></code>. Although the way they look like in this sentence is what I would like them to look like, not what they currently look. ### Status Quo Here’s a screenshot of what it currently looks like: ![Screenshot_20210105_202751](https://user-images.githubusercontent.com/3986214/103692608-4a978780-4f98-11eb-9451-e13622b2e3c0.png) With a few HTML-style code blocks, we can fix all the spacing issues in the above screenshot that are due usage of this hack/workaround of putting multiple code blocks right next to each other being used. ### after d3915c5: ![Screenshot_20210105_202932](https://user-images.githubusercontent.com/3986214/103692688-6f8bfa80-4f98-11eb-9be5-9b370eaef644.png) There’s still a problem of inconsistency. Especially in a sentence such as > A [`Pin<P>`][Pin] where `P: Deref` should be considered as a "`P`-style pointer" to _[...]_ looks weird with the variable `P` having different colors (and `Deref` has a different color from before where it was a link, too). Or compare the difference of <code>[Pin]<[Box]\<T>></code> vs [`Box<T>`][Box] where one time the variable is part of the link and the other time it isn’t. _Note: Color differences show even **more strongly** when the ayu theme is used, while they are a bit less prominent in the light theme than they are in the dark theme, which is the one used for these screenshots._ This is why I’ve added the next commit ### after ceaeb24 ![Screenshot_20210105_203113](https://user-images.githubusercontent.com/3986214/103693496-ab738f80-4f99-11eb-942d-29dace459734.png) pulling all the type parameters out of their links, and also the last commit with clearly visible changes ### after 87ac118 ![Screenshot_20210105_203252](https://user-images.githubusercontent.com/3986214/103693625-e5dd2c80-4f99-11eb-91b7-470c37934e7e.png) where more links are added, removing e.g. the inconsistency with `Deref`’s color in e.g. `P: Deref` that I already mentioned above. ## Discussion I am aware that this PR may very well be overkill. If for now only the first commit (plus the fix for the `Drop` link in e65385f, the link titles 684edf7 as far as they apply, and a few of the line-break changes) are wanted, I can reduce this PR to just those changes. I personally find the rendered result with all these changes very nice though. On the other hand, all these `<code>` tags are not very nice in the source code, I’ll admit. Perhaps alternative solutions could be preferred, such as `rustdoc` support for merging subsequent inline code blocks so that all the cases that currently use workarounds rendered as [`Box`]`<`[`Option`]`<T>>` automatically become <code>[Box]<[Option]\<T>></code> without any need for further changes. Even in this case, having a properly formatted, better looking example in the standard library docs could help motivate such a change to `rustdoc` by prodiving an example of the expected results and also the already existing alternative (i.e. using `<code>`). On the other hand, `` [`Box`]`<`[`Option`]`<T>>` `` isn’t particularly nice-looking source code either. I’m not even sure if I wouldn’t actually find the version `<code>[Box]<[Option]\<T>></code>` cleaner to read. `@rustbot` modify labels: T-doc, T-rustdoc
- Loading branch information