Add documentation for some rustc_type_ir macros - #2939
Conversation
|
Thanks for the PR. If you have write access, feel free to merge this PR if it does not need reviews. You can request a review using |
rustbot
added
the
S-waiting-on-review
5531647 to
5efc986
Compare
|
r? @lcnr |
5efc986 to
2df844b
Compare
lcnr
added
S-waiting-on-author
| **quirk 3:** | ||
| The bounds are deliberately written as associated type bounds on the `Interner` | ||
| trait rather than as `where` clauses on `LiftInto`. Given only `I: LiftInto<J>`, | ||
| Rust can then treat bounds such as the following as implied: | ||
|
|
||
| ```rust | ||
| I::Ty: Lift<J, Lifted = J::Ty> | ||
| I::Const: Lift<J, Lifted = J::Const> | ||
| ``` | ||
|
|
||
| This allows `Lift_Generic` to emit the bound `I: LiftInto<J>` while still | ||
| calling `lift_to_interner` on fields of type `I::Ty`, `I::Const`, and the other | ||
| declared associated types. It also guarantees that each call produces the | ||
| destination field type expected after the derive rewrites `I::Assoc` to | ||
| `J::Assoc`. | ||
|
|
||
| Without `declare_lift_into!`, the derive would need to generate a separate bound | ||
| for every interner-associated type used by every field. If a new `Interner` | ||
| associated type is expected to work with `Lift_Generic`, it needs an appropriate | ||
| `Lift` implementation and normally needs to be included in the | ||
| `declare_lift_into!` invocation. | ||
|
|
||
| If you want to ignore a file, such as a primitive like a `u32` which can't be | ||
| lifted you can skip the field with `#[lift(ignore)]`. |
There was a problem hiding this comment.
what exactly does that mean 🤔 feels like maybe that has less to do with the derive and more generally the way Lift works. Right now the context shift from "what does derive do" to "how does Lift work" is jarring. I think for derives the explanation should generally be "perfect derive, requires X for every field, following special cases"
maybe reframe this entire section to "derived traits", and then talk about the traits, then the "what's necessary for X to impl the trait", and then some small things about the way the derive macro works?
There was a problem hiding this comment.
8369c15 This introduces the trait, points to the source code and then describes what the macro does
056f2c0 to
6b5a58d
Compare
6b5a58d to
49ef377
Compare
|
@bors r=lcnr |
| - [`trait Lift` and `Lift_Generic`][lift-trait-macro] | ||
| - [`trait GenericTypeVisitable`][generictypevisitable] | ||
| - [`trait TypeFoldable` and `TypeFoldable_Generic`][type-foldable-trait-macro] |
There was a problem hiding this comment.
| - [`trait Lift` and `Lift_Generic`][lift-trait-macro] | |
| - [`trait GenericTypeVisitable`][generictypevisitable] | |
| - [`trait TypeFoldable` and `TypeFoldable_Generic`][type-foldable-trait-macro] | |
| - [`trait TypeFoldable` and `TypeFoldable_Generic`][type-foldable-trait-macro] | |
| - [`trait Lift` and `Lift_Generic`][lift-trait-macro] | |
| - [`trait GenericTypeVisitable`][generictypevisitable] |
:<
| The trait has two macros that can derive `TypeVisitable`, | ||
| `TypeVisitable_Generic` and [`GenericTypeVisitable`][generictypevisitable] of | ||
| which both, none or one of these macros can be used on a struct or enum. |
There was a problem hiding this comment.
that's wrong, is it not?
There was a problem hiding this comment.
The statement is correct. Whether or not the statement should be correct I am not sure;
struct PlaceHolderhas both- Rather obviously, simply not using it is possible
- Then either/or is also possible as you don't need one in order to implement the other.
There was a problem hiding this comment.
Oh that's not what you were referring to. Yes the statement is wrong, you are correct
| While ostensibly similar due to their names, they implement two different | ||
| visiting systems. | ||
|
|
||
| - `TypeVisitable_Generic` means: derive the ordinary `TypeVisitable` trait | ||
| generically over an `Interner`. | ||
| - `GenericTypeVisitable` means: derive the separate `GenericTypeVisitable` trait | ||
| used by non-nightly consumers such as rust-analyzer. | ||
|
|
||
| As such a struct or enum can derive both `TypeVisitable_Generic` and | ||
| `GenericTypeVisitable` |
There was a problem hiding this comment.
move this to the GenericTypeVisitable secton
| #### `TypeVisitable_Generic` | ||
| [typevisitable_generic]: #typevisitable_generic |
There was a problem hiding this comment.
is that header now unnecessary, don't have it for TypeFoldable
There was a problem hiding this comment.
I have the header type-foldable-trait-macro
3 participants
Adds documentation for;
TypeVisitable_GenericTypeFoldable_GenericLift_GenericGenericTypeVisitableFollows a formulaic "<macro_name>, description, how to use it, What its expansion does"