Improve links in inline code in `core::pin`.
## Context
So I recently opened #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:
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 d3915c555e:
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 ceaeb249a3
pulling all the type parameters out of their links, and also the last commit with clearly visible changes
### after 87ac118ba3
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 e65385fbfa, the link titles 684edf7a70 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
Remove the insta-stable `cfg(wasm)`
The addition of `cfg(wasm)` was an oversight on my end that turns out to have a number
of downsides:
* It was introduced as an insta-stable addition, forgoing the usual
staging mechanism we use for potentially far-reaching changes;
* It is a breaking change for people who are using `--cfg wasm` either
directly or via cargo for other purposes;
* It is not entirely clear if a bare `wasm` cfg is a right option or
whether `wasm` family of targets are special enough to warrant
special-casing these targets specifically.
As for the last point, there appears to be a fair amount of support for
reducing the boilerplate in specifying architectures from the same
family, while ignoring their pointer width. The suggested way forward
would be to propose such a change as a separate RFC as it is potentially
a quite contentious addition.
cc #83879 `@devsnek`
rustdoc: Link to the docs on namespaces when an unknown disambiguator is found
cc https://github.com/rust-lang/rust/issues/83859
`@lopopolo` does this look about like what you expected?
r? `@camelid`
Rollup of 5 pull requests
Successful merges:
- #82497 (Fix handling of `--output-format json` flag)
- #83689 (Add more info for common trait resolution and async/await errors)
- #83952 (Account for `ExprKind::Block` when suggesting .into() and deref)
- #83965 (Add Debug implementation for hir::intravisit::FnKind)
- #83974 (Fix outdated crate names in `rustc_interface::callbacks`)
Failed merges:
r? `@ghost`
`@rustbot` modify labels: rollup
Add more info for common trait resolution and async/await errors
* Suggest `Pin::new`/`Box::new`/`Arc::new`/`Box::pin` in more cases
* Point at `impl` and type defs introducing requirements on E0277
Fix handling of `--output-format json` flag
- Don't treat it as deprecated on stable and beta channels. Before, it
would give confusing and incorrect output:
```
warning: the 'output-format' flag is considered deprecated
|
= warning: see issue #44136 <https://github.com/rust-lang/rust/issues/44136> for more information
error: json output format isn't supported for doc generation
```
Both of those are wrong: output-format isn't deprecated, and json
output is supported.
- Require -Z unstable-options for `--output-format json`
Previously, it was allowed by default on nightly, which made it hard
to realize the flag wouldn't be accepted on beta or stable.
To get the test working I had to remove `-Z unstable-options`, which x.py passed to compiletest unconditionally. It was first added in 8c2ec689c1 so `-Z miri` would be allowed. -Z miri is no longer passed unconditionally, so hopefully removing it won't break anything.
r? ```@aDotInTheVoid``` cc ```@HeroicKatora``` ```@CraftSpider```
Thanks to ```@memoryruins``` for pointing it out on Discord!
cc ```@Mark-Simulacrum``` for the change to compiletest.
Cleanup option parsing and config.toml.example
- Add an assertion that `link-shared = true` when `thin-lto = true`.
Previously, link-shared would be silently overwritten.
- Get rid of `Option<bool>` in bootstrap/config.rs. Set defaults
immediately instead of delaying until later in bootstrap. This makes
it easier to find what the default value is.
- Remove redundant `config.x = false` when the default was already false
- Set defaults for `bindir` in `default_opts()` instead of `parse()`
- Update `download-ci-llvm = if-supported` option to match bootstrap.py
- Remove redundant check for link_shared. Previously, it was checked twice.
- Update various options in config.toml.example to their defaults.
Previously, some options showed an example value instead of the
default value.
- Fix incorrect defaults in config.toml.example
+ `use-libcxx` defaults to false
+ Add missing `check-stage = 0`
+ Update several defaults to be conditional (e.g. `if incremental { 10 } else { 100 }`)
- Remove redundant defaults in prose
- Use the same comment for the default and target-dependent `musl-root`
- Fix typos
- Link to `cc_detect` for `cc` and `cxx`, since the logic is ... complicated.
- Update more defaults to better reflect how they actually get set
- Remove ignored `gpg-password-file` option
This stopped being used in
7704d35,
but was never removed from config.toml.
- Remove unused flags from `config.toml`
+ Disallow `infodir` and `localstatedir` in `config.toml`
+ Allow the flags in `./configure`, but give a warning that they will be
ignored.
+ Fix incorrect comment that `datadir` will be ignored.
Example output:
```
$ ./configure --set install.infodir=xxx
configure: processing command line
configure:
configure: install.infodir := xxx
configure: build.configure-args := ['--set', 'install.infodir=xxx']
warning: infodir will be ignored
configure:
configure: writing `config.toml` in current directory
configure:
configure: run `python /home/joshua/rustc3/x.py --help`
configure:
```
- Update CHANGELOG
cc https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler/topic/bootstrap.20defaults
The addition of `cfg(wasm)` was an oversight on my end that has a number
of downsides:
* It was introduced as an insta-stable addition, forgoing the usual
staging mechanism we use for potentially far-reaching changes;
* It is a breaking change for people who are using `--cfg wasm` either
directly or via cargo for other purposes;
* It is not entirely clear if a bare `wasm` cfg is a right option or
whether `wasm` family of targets are special enough to warrant
special-casing these targets specifically.
As for the last point, there appears to be a fair amount of support for
reducing the boilerplate in specifying architectures from the same
family, while ignoring their pointer width. The suggested way forward
would be to propose such a change as a separate RFC as it is potentially
a quite contentious addition.
- Add an assertion that `link-shared = true` when `thin-lto = true`.
Previously, link-shared would be silently overwritten.
- Get rid of `Option<bool>` in bootstrap/config.rs. Set defaults
immediately instead of delaying until later in bootstrap. This makes
it easier to find what the default value is.
- Remove redundant `config.x = false` when the default was already false
- Set defaults for `bindir` in `default_opts()` instead of `parse()`
- Update `download-ci-llvm = if-supported` option to match bootstrap.py
- Remove redundant check for link_shared. Previously, it was checked twice.
- Update various options in config.toml.example to their defaults.
Previously, some options showed an example value instead of the
default value.
- Fix incorrect defaults in config.toml.example
+ `use-libcxx` defaults to false
+ Add missing `check-stage = 0`
+ Update several defaults to be conditional (e.g. `if incremental { 10 } else { 100 }`)
- Remove redundant defaults in prose
- Use the same comment for the default and target-dependent `musl-root`
- Fix typos
- Link to `cc_detect` for `cc` and `cxx`, since the logic is ... complicated.
- Update more defaults to better reflect how they actually get set
- Remove ignored `gpg-password-file` option
This stopped being used in
7704d35acc,
but was never removed from config.toml.
- Remove unused flags from `config.toml`
+ Disallow `infodir` and `localstatedir` in `config.toml`
+ Allow the flags in `./configure`, but give a warning that they will be
ignored.
+ Fix incorrect comment that `datadir` will be ignored.
Example output:
```
$ ./configure --set install.infodir=xxx
configure: processing command line
configure:
configure: install.infodir := xxx
configure: build.configure-args := ['--set', 'install.infodir=xxx']
warning: infodir will be ignored
configure:
configure: writing `config.toml` in current directory
configure:
configure: run `python /home/joshua/rustc3/x.py --help`
configure:
```
- Update CHANGELOG
- Add "as an example" where appropriate
- Link to an issue instead of to ephemeral chats
Stabilize cmp_min_max_by
I would like to propose cmp::{min_by, min_by_key, max_by, max_by_key}
for stabilization.
These are relatively simple and seemingly uncontroversial functions and
have been unchanged in unstable for a while now.
Closes: #64460
Rollup of 8 pull requests
Successful merges:
- #83476 (Add strong_count mutation methods to Rc)
- #83634 (Do not emit the advanced diagnostics on macros)
- #83816 (Trigger `unused_doc_comments` on macros at once)
- #83916 (Use AnonConst for asm! constants)
- #83935 (forbid `impl Trait` in generic param defaults)
- #83936 (Disable using non-ascii identifiers in extern blocks.)
- #83945 (Add suggestion to reborrow mutable references when they're moved in a for loop)
- #83954 (Do not ICE when closure is involved in Trait Alias Impl Trait)
Failed merges:
r? `@ghost`
`@rustbot` modify labels: rollup
I would like to propose cmp::{min_by, min_by_key, max_by, max_by_key}
for stabilization.
These are relatively simple and seemingly uncontroversial functions and
have been unchanged in unstable for a while now.
use a `SmallVec` in `impl_or_trait_item`
#83293 showed that this is fairly hot, slightly improves max-rss and cpu cycles, does not noticeably improve instruction counts
forbid `impl Trait` in generic param defaults
Fixes#83929
Forbid using `impl Trait` in the default types of generic parameters, e.g. `struct Foo<T = impl Trait>`. I assume this was never supposed to be allowed - it seems no UI test used it.
Note that using `impl Trait` in this position did not hit a feature gate error; however, this *shouldn't* be a breaking change as any attempt to use it should have hit the ICE in #83929 and/or failed to provide a defining use of the `impl Trait`.
Use AnonConst for asm! constants
This replaces the old system which used explicit promotion. See #83169 for more background.
The syntax for `const` operands is still the same as before: `const <expr>`.
Fixes#83169
Because the implementation is heavily based on inline consts, we suffer from the same issues:
- We lose the ability to use expressions derived from generics. See the deleted tests in `src/test/ui/asm/const.rs`.
- We are hitting the same ICEs as inline consts, for example #78174. It is unlikely that we will be able to stabilize this before inline consts are stabilized.
Add strong_count mutation methods to Rc
The corresponding methods were stabilized on `Arc` in #79285 (tracking: #71983). This patch implements and stabilizes identical methods on the `Rc` types as well.
rustdoc: Store intra-doc links in Cache instead of on items directly
Items are first built after rustdoc creates the TyCtxt. To allow
resolving the links before the TyCtxt is built, the links can't be
stored on `clean::Item` directly.
Helps with https://github.com/rust-lang/rust/issues/83761. Opening this early because I think it might decrease memory usage.
rustdoc: Use `ThinVec` in a few places
Almost every crate has no primitives and no keywords defined in it, so
using `ThinVec` should make some types smaller.
- Don't treat it as deprecated on stable and beta channels. Before, it
would give confusing and incorrect output:
```
warning: the 'output-format' flag is considered deprecated
|
= warning: see issue #44136 <https://github.com/rust-lang/rust/issues/44136> for more information
error: json output format isn't supported for doc generation
```
Both of those are wrong: output-format isn't deprecated, and json
output is supported.
- Require -Z unstable-options for `--output-format json`
Previously, it was allowed by default on nightly, which made it hard
to realize the flag wouldn't be accepted on beta or stable.
Note that this still allows `--output-format html`, which has been
stable since 1.0.
- Remove unnecessary double-checking of the feature gate when parsing
the output format
- Add custom run-make test since compiletest passes -Zunstable-options
by default
