Flesh out the "representing types" chapter #1985

BoxyUwU · 2024-05-27T21:11:46Z

I added a section about how we define generic parameters since explaining ty::Generics seemed like useful context for explaining TyKind::Param (and friends). I moved the section on early vs late bound parameters under this chapter since it seems like the natural place for this to live.

I moved the section on the fold module out of the chapter on representing types since it doesn't really have anything to do with how (or why) we structure Ty/Const/Region the way that we do.

As for the changes to the representing types chapter:

Moved discussion of TyKind::Adt/GenericArgs into a single chapter as previously we were discussing these things split across three different files
Split "bound vars and params" into a section solely about generic parameters and a separate section about Binder
Discuss EarlyBinder and what we use it for and
Talk about placeholders ty/const/regions

src/what_is_ty_generics.md

src/ty.md

src/ty_module/generic_arguments.md

src/ty_module/param_ty_const_regions.md

src/ty_module/binders.md

src/ty_module/param_ty_const_regions.md

src/ty_module/early_binder.md

src/ty_module/instantiating_binders.md

BoxyUwU · 2024-05-30T01:42:58Z

cc @lcnr

lcnr

saying "generic parameters introduced via for<'a> syntax" feels wrong, you introduce bound variables, not generic parameters (except for late bound fn args, which are somewhere in the middle. I don't know of a better alternative to introducing these concepts, so I think it may actually be useful to slightly muddle these concepts.

I am quite happy with these changes and think they're an improvement. Feel free to merge after handling as many nits as you want. Don't want to block this from getting merged, given that it's already really useful and the nits don't change anything fundamental

src/ty_module/binders.md

src/ty_module/early_binder.md

lcnr · 2024-05-30T23:45:17Z

src/ty_module/early_binder.md

+**Note on indices:** It is possible for the indices in `Param` to not match with what the `EarlyBinder` binds. For
+example, the index could be out of bounds or it could be the index of a lifetime when we were expecting a type.
+These sorts of errors would be caught earlier in the compiler when translating from a `rustc_hir::Ty` to a `ty::Ty`.
+If they occur later, that is a compiler bug.


Suggested change

**Note on indices:** It is possible for the indices in `Param` to not match with what the `EarlyBinder` binds. For

example, the index could be out of bounds or it could be the index of a lifetime when we were expecting a type.

These sorts of errors would be caught earlier in the compiler when translating from a `rustc_hir::Ty` to a `ty::Ty`.

If they occur later, that is a compiler bug.

**Note on indices:** It is a bug if the indices in `Param` to not match with what the `EarlyBinder` binds. For example, the index could be out of bounds or it could be the index of a lifetime when we were expecting a type. This should get catched when translating from a `rustc_hir::Ty` to a `ty::Ty`.

Do we ever intentionally move EarlyBinder around while it has wrong params?

I'm not entirely sure without going through every usage of EarlyBinder in the compiler. Nothing comes to mind though and if we have code that does so I'd be a bit :(. Ideally we could store a DefId in EarlyBinder to explicitly track the generics it binds like we do with Binder imo. The whole setup with opaque types' generics_of is sketchy enough that it might actually catch some bugs lol

lcnr · 2024-05-30T23:47:54Z

src/ty_module/early_binder.md

+When constructing a `Ty` to represent the `b` parameter's type we need to get the type of `Self` on the impl that we are inside. This can be acquired by calling the [`type_of`] query with the `impl`'s `DefId`, however, this will return a `EarlyBinder<Ty>` as the impl block binds generic parameters that may have to be discharged if we are outside of the impl.
+
+The `EarlyBinder` type provides an [`instantiate_identity`] function for discharging the binder when you are "already inside of it". Conceptually this discharges the binder by instantiating it with placeholders in the root universe (we will talk about what this means in the next few chapters). In practice though it simply returns the inner value with no modification taking place.


I personally consider instantiate_identity to be a more performant version of the noop EarlyBinder::instantiate(GenericArgs::identity_for_item(..)). I would mention that before talking about placeholders. feel free to implement that suggestion as you see fit

Added a little sentence about this

src/ty_module/instantiating_binders.md

src/ty_module/param_ty_const_regions.md

Update books ## rust-lang/book 6 commits in 85442a608426d3667f1c9458ad457b241a36b569..5228bfac8267ad24659a81b92ec5417976b5edbc 2024-05-29 20:55:49 UTC to 2024-05-27 17:22:03 UTC - Fix typo in ch10-03 (rust-lang/book#3539) - Backport changes to ch 9 and 10 (rust-lang/book#3946) - infra: correctly support preprocessors for nostarch (rust-lang/book#3944) - Use `<kbd>` instead of `<span class="keystroke">` (rust-lang/book#3945) - infra: Fix clippy warning in remove_markup (rust-lang/book#3943) - fix: ch10-03 - misleading use of expect on .split (rust-lang/book#3939) ## rust-lang/edition-guide 2 commits in 0c68e90acaae5a611f8f5098a3c2980de9845ab2..bbaabbe088e21a81a0d9ae6757705020d5d7b416 2024-05-24 19:07:18 UTC to 2024-05-21 22:40:52 UTC - 2024: Document reserving `gen` keyword (rust-lang/edition-guide#300) - 2024: Document cargo changes (rust-lang/edition-guide#301) ## rust-embedded/book 1 commits in dd962bb82865a5284f2404e5234f1e3222b9c022..b10c6acaf0f43481f6600e95d4b5013446e29f7a 2024-05-31 08:51:50 UTC to 2024-05-31 08:51:50 UTC - Add some explanations as to why exception re-entrancy may still be an issue in a multicore-environment. (rust-embedded/book#367) ## rust-lang/reference 6 commits in e356977fceaa8591c762312d8d446769166d4b3e..6019b76f5b28938565b251bbba0bf5cc5c43d863 2024-06-03 15:58:57 UTC to 2024-05-25 18:35:54 UTC - Add Apple `target_abi` values to the example values (rust-lang/reference#1507) - this needs a space (rust-lang/reference#1506) - Mention Variadics With No Fixed Parameter (rust-lang/reference#1494) - Add "scopes" chapter. (rust-lang/reference#1040) - update patterns.md for const pattern RFC (rust-lang/reference#1456) - document guarantee about evaluation of associated consts and const blocks (rust-lang/reference#1497) ## rust-lang/rust-by-example 3 commits in 20482893d1a502df72f76762c97aed88854cdf81..4840dca06cadf48b305d3ce0aeafde7f80933f80 2024-05-28 13:56:12 UTC to 2024-05-27 11:51:10 UTC - Update mdbook-i18n-helpers to 0.3.3 (rust-lang/rust-by-example#1857) - Fix CI failure (rust-lang/rust-by-example#1856) - Add precision on From/Into asymmetry to from_into.md (rust-lang/rust-by-example#1855) ## rust-lang/rustc-dev-guide 4 commits in b6d4a4940bab85cc91eec70cc2e3096dd48da62d..6a7374bd87cbac0f8be4fd4877d8186d9c313985 2024-05-31 00:27:28 UTC to 2024-05-21 09:56:12 UTC - Flesh out the "representing types" chapter (rust-lang/rustc-dev-guide#1985) - sync the stage0 filename (rust-lang/rustc-dev-guide#1979) - Add Rust for Linux notification group entry (rust-lang/rustc-dev-guide#1984) - fix some typos (rust-lang/rustc-dev-guide#1983)

Rollup merge of rust-lang#125933 - rustbot:docs-update, r=ehuss Update books ## rust-lang/book 6 commits in 85442a608426d3667f1c9458ad457b241a36b569..5228bfac8267ad24659a81b92ec5417976b5edbc 2024-05-29 20:55:49 UTC to 2024-05-27 17:22:03 UTC - Fix typo in ch10-03 (rust-lang/book#3539) - Backport changes to ch 9 and 10 (rust-lang/book#3946) - infra: correctly support preprocessors for nostarch (rust-lang/book#3944) - Use `<kbd>` instead of `<span class="keystroke">` (rust-lang/book#3945) - infra: Fix clippy warning in remove_markup (rust-lang/book#3943) - fix: ch10-03 - misleading use of expect on .split (rust-lang/book#3939) ## rust-lang/edition-guide 2 commits in 0c68e90acaae5a611f8f5098a3c2980de9845ab2..bbaabbe088e21a81a0d9ae6757705020d5d7b416 2024-05-24 19:07:18 UTC to 2024-05-21 22:40:52 UTC - 2024: Document reserving `gen` keyword (rust-lang/edition-guide#300) - 2024: Document cargo changes (rust-lang/edition-guide#301) ## rust-embedded/book 1 commits in dd962bb82865a5284f2404e5234f1e3222b9c022..b10c6acaf0f43481f6600e95d4b5013446e29f7a 2024-05-31 08:51:50 UTC to 2024-05-31 08:51:50 UTC - Add some explanations as to why exception re-entrancy may still be an issue in a multicore-environment. (rust-embedded/book#367) ## rust-lang/reference 6 commits in e356977fceaa8591c762312d8d446769166d4b3e..6019b76f5b28938565b251bbba0bf5cc5c43d863 2024-06-03 15:58:57 UTC to 2024-05-25 18:35:54 UTC - Add Apple `target_abi` values to the example values (rust-lang/reference#1507) - this needs a space (rust-lang/reference#1506) - Mention Variadics With No Fixed Parameter (rust-lang/reference#1494) - Add "scopes" chapter. (rust-lang/reference#1040) - update patterns.md for const pattern RFC (rust-lang/reference#1456) - document guarantee about evaluation of associated consts and const blocks (rust-lang/reference#1497) ## rust-lang/rust-by-example 3 commits in 20482893d1a502df72f76762c97aed88854cdf81..4840dca06cadf48b305d3ce0aeafde7f80933f80 2024-05-28 13:56:12 UTC to 2024-05-27 11:51:10 UTC - Update mdbook-i18n-helpers to 0.3.3 (rust-lang/rust-by-example#1857) - Fix CI failure (rust-lang/rust-by-example#1856) - Add precision on From/Into asymmetry to from_into.md (rust-lang/rust-by-example#1855) ## rust-lang/rustc-dev-guide 4 commits in b6d4a4940bab85cc91eec70cc2e3096dd48da62d..6a7374bd87cbac0f8be4fd4877d8186d9c313985 2024-05-31 00:27:28 UTC to 2024-05-21 09:56:12 UTC - Flesh out the "representing types" chapter (rust-lang/rustc-dev-guide#1985) - sync the stage0 filename (rust-lang/rustc-dev-guide#1979) - Add Rust for Linux notification group entry (rust-lang/rustc-dev-guide#1984) - fix some typos (rust-lang/rustc-dev-guide#1983)

BoxyUwU added 2 commits May 27, 2024 21:57

Introduce chapter for defining generic parameters

2efb463

Rewrite the "representing types" section to be more comprehensive

5d808a5