Improve the function pointer docs
This is #97842 but for function pointers instead of tuples. The concept is basically the same.
* Reduce duplicate impls; show `fn (T₁, T₂, …, Tₙ)` and include a sentence saying that there exists up to twelve of them.
* Show `Copy` and `Clone`.
* Show auto traits like `Send` and `Sync`, and blanket impls like `Any`.
https://notriddle.com/notriddle-rustdoc-test/std/primitive.fn.html
Remove most box syntax from librustdoc
This is the second attempt after the librustdoc specific changes have been reverted from #87781 in #89134, due to a minor, but exant regression caused by the changes. ~~There have been some changes to librustdoc in the past and maybe thanks to them there is no regression any more. If there is still a regression, one can investigate further and maybe find ways to fix the regressions. Thus, i request a perf run.~~ Edit: turns out there is still a regression, but it's caused only by a subset of the changes. So I've changed this PR to only contains the changes that don't cause any performance regressions, keeping the regression causing changes for a later PR.
This commit adds a new unstable attribute, `#[doc(tuple_varadic)]`, that
shows a 1-tuple as `(T, ...)` instead of just `(T,)`, and links to a section
in the tuple primitive docs that talks about these.
Lifetime variance fixes for rustdoc
#97287 migrates rustc to a `Ty` type that is invariant over its lifetime `'tcx`, so I need to fix a bunch of places that assume that `Ty<'a>` and `Ty<'b>` can be unified by shortening both to some common lifetime.
This is doable, since everything is already `'tcx`, so all this PR does is be a bit more explicit that elided lifetimes are actually `'tcx`.
Split out from #97287 so the rustdoc team can review independently.
rustdoc: Reduce clean::Type size
There is no need to keep the `DefId` around since it's allow used to compute if we should show a cast or not. As such, we can simply directly store the boolean.
I think it's not what you had in mind `@camelid` but I guess it's still an improvement? 😉
It was discussed in https://github.com/rust-lang/rust/pull/93941.
r? `@camelid`
With #93803 `impl Trait` function arguments get desugared to hidden
where bounds. However, Clippy needs to know if a bound was originally a
impl Trait or an actual bound. This adds a field to the
`WhereBoundPredicate` struct to keep track of this information during
HIR lowering.
Only crate root def-ids don't have a parent, and in majority of cases the argument of `DefIdTree::parent` cannot be a crate root.
So we now panic by default in `parent` and introduce a new non-panicing function `opt_parent` for cases where the argument can be a crate root.
Same applies to `local_parent`/`opt_local_parent`.
librustdoc: adopt let else in more places
Continuation of #89933, #91018, #91481, #93046, #93590, #94011.
I have extended my clippy lint to also recognize tuple passing and match statements. The diff caused by fixing it is way above 1 thousand lines. Thus, I split it up into multiple pull requests to make reviewing easier. This PR handles librustdoc.
Improve `AdtDef` interning.
This commit makes `AdtDef` use `Interned`. Much of the commit is tedious
changes to introduce getter functions. The interesting changes are in
`compiler/rustc_middle/src/ty/adt.rs`.
r? `@fee1-dead`
This commit makes `AdtDef` use `Interned`. Much the commit is tedious
changes to introduce getter functions. The interesting changes are in
`compiler/rustc_middle/src/ty/adt.rs`.
This updates the standard library's documentation to use the new syntax. The
documentation is worthwhile to update as it should be more idiomatic
(particularly for features like this, which are nice for users to get acquainted
with). The general codebase is likely more hassle than benefit to update: it'll
hurt git blame, and generally updates can be done by folks updating the code if
(and when) that makes things more readable with the new format.
A few places in the compiler and library code are updated (mostly just due to
already having been done when this commit was first authored).
Support GATs in Rustdoc
Implements:
1. Rendering GATs in trait definitions and impl blocks
2. Rendering GATs in types (e.g. in the return type of a function)
Fixes#92341
This is my first rustdoc PR, so I have absolutely no idea how to produce tests for this. Advice from the rustdoc team would be wonderful!
I tested locally and things looked correct:
Specifically, rename the `Const` struct as `ConstS` and re-introduce `Const` as
this:
```
pub struct Const<'tcx>(&'tcx Interned<ConstS>);
```
This now matches `Ty` and `Predicate` more closely, including using
pointer-based `eq` and `hash`.
Notable changes:
- `mk_const` now takes a `ConstS`.
- `Const` was copy, despite being 48 bytes. Now `ConstS` is not, so need a
we need separate arena for it, because we can't use the `Dropless` one any
more.
- Many `&'tcx Const<'tcx>`/`&Const<'tcx>` to `Const<'tcx>` changes
- Many `ct.ty` to `ct.ty()` and `ct.val` to `ct.val()` changes.
- Lots of tedious sigil fiddling.
Specifically, change `Region` from this:
```
pub type Region<'tcx> = &'tcx RegionKind;
```
to this:
```
pub struct Region<'tcx>(&'tcx Interned<RegionKind>);
```
This now matches `Ty` and `Predicate` more closely.
Things to note
- Regions have always been interned, but we haven't been using pointer-based
`Eq` and `Hash`. This is now happening.
- I chose to impl `Deref` for `Region` because it makes pattern matching a lot
nicer, and `Region` can be viewed as just a smart wrapper for `RegionKind`.
- Various methods are moved from `RegionKind` to `Region`.
- There is a lot of tedious sigil changes.
- A couple of types like `HighlightBuilder`, `RegionHighlightMode` now have a
`'tcx` lifetime because they hold a `Ty<'tcx>`, so they can call `mk_region`.
- A couple of test outputs change slightly, I'm not sure why, but the new
outputs are a little better.
Specifically, change `Ty` from this:
```
pub type Ty<'tcx> = &'tcx TyS<'tcx>;
```
to this
```
pub struct Ty<'tcx>(Interned<'tcx, TyS<'tcx>>);
```
There are two benefits to this.
- It's now a first class type, so we can define methods on it. This
means we can move a lot of methods away from `TyS`, leaving `TyS` as a
barely-used type, which is appropriate given that it's not meant to
be used directly.
- The uniqueness requirement is now explicit, via the `Interned` type.
E.g. the pointer-based `Eq` and `Hash` comes from `Interned`, rather
than via `TyS`, which wasn't obvious at all.
Much of this commit is boring churn. The interesting changes are in
these files:
- compiler/rustc_middle/src/arena.rs
- compiler/rustc_middle/src/mir/visit.rs
- compiler/rustc_middle/src/ty/context.rs
- compiler/rustc_middle/src/ty/mod.rs
Specifically:
- Most mentions of `TyS` are removed. It's very much a dumb struct now;
`Ty` has all the smarts.
- `TyS` now has `crate` visibility instead of `pub`.
- `TyS::make_for_test` is removed in favour of the static `BOOL_TY`,
which just works better with the new structure.
- The `Eq`/`Ord`/`Hash` impls are removed from `TyS`. `Interned`s impls
of `Eq`/`Hash` now suffice. `Ord` is now partly on `Interned`
(pointer-based, for the `Equal` case) and partly on `TyS`
(contents-based, for the other cases).
- There are many tedious sigil adjustments, i.e. adding or removing `*`
or `&`. They seem to be unavoidable.
Remove defaultness from ImplItem.
This information is not really used anywhere, except HIR pretty-printing. This makes ImplItem and TraitItem more similar.
Lazy type-alias-impl-trait
Previously opaque types were processed by
1. replacing all mentions of them with inference variables
2. memorizing these inference variables in a side-table
3. at the end of typeck, resolve the inference variables in the side table and use the resolved type as the hidden type of the opaque type
This worked okayish for `impl Trait` in return position, but required lots of roundabout type inference hacks and processing.
This PR instead stops this process of replacing opaque types with inference variables, and just keeps the opaque types around.
Whenever an opaque type `O` is compared with another type `T`, we make the comparison succeed and record `T` as the hidden type. If `O` is compared to `U` while there is a recorded hidden type for it, we grab the recorded type (`T`) and compare that against `U`. This makes implementing
* https://github.com/rust-lang/rfcs/pull/2515
much simpler (previous attempts on the inference based scheme were very prone to ICEs and general misbehaviour that was not explainable except by random implementation defined oddities).
r? `@nikomatsakis`
fixes#93411fixes#88236
by using an opaque type obligation to bubble up comparisons between opaque types and other types
Also uses proper obligation causes so that the body id works, because out of some reason nll uses body ids for logic instead of just diagnostics.
Render more readable macro matcher tokens in rustdoc
Follow-up to #92334.
This PR lifts some of the token rendering logic from https://github.com/dtolnay/prettyplease into rustdoc so that even the matchers for which a source code snippet is not available (because they are macro-generated, or any other reason) follow some baseline good assumptions about where the tokens in the macro matcher are appropriate to space.
The below screenshots show an example of the difference using one of the gnarliest macros I could find. Some things to notice:
- In the **before**, notice how a couple places break in between `$(....)`↵`*`, which is just about the worst possible place that it could break.
- In the **before**, the lines that wrapped are weirdly indented by 1 space of indentation relative to column 0. In the **after**, we use the typical way of block indenting in Rust syntax which is put the open/close delimiters on their own line and indent their contents by 4 spaces relative to the previous line (so 8 spaces relative to column 0, because the matcher itself is indented by 4 relative to the `macro_rules` header).
- In the **after**, macro_rules metavariables like `$tokens:tt` are kept together, which is how just about everybody writing Rust today writes them.
## Before
## After
r? `@camelid`
This is the same idea as #92533, but for `AssocItem` instead
of `VariantDef`/`FieldDef`.
With this change, we no longer have any uses of
`#[stable_hasher(project(...))]`
Replace use of `ty()` on term and use it in more places. This will allow more flexibility in the
future, but slightly worried it allows items which are consts which only accept types.
ProjectionPredicate should be able to handle both associated types and consts so this adds the
first step of that. It mainly just pipes types all the way down, not entirely sure how to handle
consts, but hopefully that'll come with time.
The field is also renamed from `ident` to `name. In most cases,
we don't actually need the `Span`. A new `ident` method is added
to `VariantDef` and `FieldDef`, which constructs the full `Ident`
using `tcx.def_ident_span()`. This method is used in the cases
where we actually need an `Ident`.
This makes incremental compilation properly track changes
to the `Span`, without all of the invalidations caused by storing
a `Span` directly via an `Ident`.
This commit removes the first of nine Clean impls on tuples, converting
it to a function instead.
The fact that these are impls causes several problems:
1. They are nameless, so it's unclear what they do.
2. It's hard to find where they're used apart from removing them and
seeing what errors occur (this applies to all Clean impls, not just
the tuple ones).
3. Rustc doesn't currently warn when impls are unused, so dead code
can accumulate easily (all Clean impls).
4. Their bodies often use tuple field indexing syntax (e.g., `self.1`)
to refer to their "arguments", which makes reading the code more
difficult.
As I noted, some of these problems apply to all Clean impls, but even
those problems are exacerbated by the tuple impls since they make
general understanding of the code harder.
Converting the impls to functions solves all four of these problems.
I would like to rename it to `Type::Path`, but then it can't be
re-exported since the name would conflict with the `Path` struct.
Usually enum variants are referred to using their qualified names in
Rust (and parts of rustdoc already do that with `clean::Type`), so this
is also more consistent with the language.
Avoid documenting top-level private imports
PR #88447 aimed to make rustdoc's `--document-private-items` mode only document imports that are visible outside the importing module. Unfortunately, I inadvertently set things up so that imports at the crate top-level are always documented, regardless of their visibility. This behavior was unintended and is [not desirable](https://github.com/rust-lang/rust/issues/90865#issuecomment-971172649).
This PR treats top-level imports as never being visible outside their parent module. In practice, the only way a top-level import can be visible externally is if it's fully public, and there's a seperate check for that.
It's worth calling attention to the fact that this change means that `pub(crate)` imports will be visible in lower level modules, but not at the top-level. This is because, at the top level of the crate, `pub(crate)` means the same thing as `pub(self)`.
It turned out that there were existing tests checking for the only behavior, which I didn't notice at the time of my previous PR. I have updated them to check for the new behavior and substantially extended them to handle differences between the top-level module and lower level modules. I may have gone overboard, so please tell me if there's anything I should cut.
r? `@jyn514`
Fixes#90865.
rustdoc: Replace where-bounded Clean impl with simple function
This is the first step in removing the Clean impls for tuples. Either way, this
significantly simplifies the code since it reduces the amount of "trait magic".
(To clarify, I'm referring to impls like `impl Clean for (A, B)`, not Clean impls
that work on tuples in the user's program.)
cc ``@jyn514``
This function parameter attribute was introduced in https://github.com/rust-lang/rust/pull/44866 as an intermediate step in implementing `impl Trait`, it's not necessary or used anywhere by itself.
Otherwise, rustdoc panics with messages like this:
thread 'rustc' panicked at 'assertion failed: cx.impl_trait_bounds.is_empty()',
src/librustdoc/clean/utils.rs:462:5
This ordering requirement is unrelated to the `clean_fn_decl_with_args`
refactoring, but the requirement was uncovered as part of that change.
I'm not sure if *all* of these places have the requirement, but I added
comments to them just in case.
Basically, this entails moving the arguments cleaning to the call site.
I extracted several local variables because:
1. It makes the code easier to read and understand.
2. If I hadn't, the extra `clean()` calls would have caused complicated
tuples to be split across several lines.
3. I couldn't just extract local variables for `args` because then the
arguments would be cleaned *before* the generics, while rustdoc expects
them to be cleaned *after*. Only extracting `args` caused panics like
this:
thread 'rustc' panicked at 'assertion failed: cx.impl_trait_bounds.is_empty()',
src/librustdoc/clean/utils.rs:462:5
Extracting variables makes the control flow -- and the required
order of cleaning -- more explicit.
This was the only Clean impl I found with `where` bounds.
This impl was doubly-confusing: it was implemented on a tuple and it
was polymorphic. Combined, this caused a "spooky action at a distance"
effect to make the code very confusing.
Merge `DocContext.{ty,lt,ct}_substs` into one map
It should be impossible to have more than one entry with a particular
key across the three maps, so they should be one map. In addition to
making it impossible for multiple entries to exist, this should improve
memory usage since now only one map is allocated on the stack and heap.
r? `@GuillaumeGomez`
This change has two advantages:
1. It makes the possible states clearer, and it makes it impossible to
construct invalid states, such as a blanket impl that is also an auto
trait impl.
2. It shrinks the size of `Impl` a bit, since now there is only one
field, rather than two.
It should be impossible to have more than one entry with a particular
key across the three maps, so they should be one map. In addition to
making it impossible for multiple entries to exist, this should improve
memory usage since now only one map is allocated on the stack and heap.
It should be preferred over `def_id_no_primitives()`, so it should have
a shorter name. I also put it before `def_id_no_primitives()` so that it
shows up first in the docs.
