Skip to content

docs(unstable-book): Document const generics features#155543

Open
popzxc wants to merge 4 commits intorust-lang:mainfrom
popzxc:document-generic-const-features
Open

docs(unstable-book): Document const generics features#155543
popzxc wants to merge 4 commits intorust-lang:mainfrom
popzxc:document-generic-const-features

Conversation

@popzxc
Copy link
Copy Markdown
Contributor

@popzxc popzxc commented Apr 20, 2026

View all comments

Relevant tracking issues: #113521 #132980 #76560 #151972

What

Adds a high-level overview of 4 unstable features related to const generic exprs.

Why

While trying to learn about the current state of const generic exprs, I found it a bit too hard due to lack of documentation -- had to read through a bunch of tracking issues & look for PRs/examples in the repo just to understand what the feature is about.

Moreover, given that there is a bunch of features with similarly-looking names, it was even more confusing. For that purpose, I also added cross-referencing across (directly or logically) related features.

As a result, I decided to add some more context to the unstable book, so that new readers have an easier time than I had.

Caveats

I understand that the features are incomplete/experimental, so the docs are at risk of becoming stale, but the book entrypoint already has a corresponding warning, so I guess it should be fine.

Also, given that I did research myself, the examples provided might be not the best to showcase the feature -- happy to provide better examples, if you have suggestions. The examples provided are what "made the feature make sense" to me as an outsider, so there is a chance that they will be good for other external readers too, though.

LLM use disclosue: an LLM was used for self-review only; research, coming up with examples, and writing is mine. Issues reported by LLM were fixed manually too.

r? @BoxyUwU

@rustbot rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Apr 20, 2026
@rustbot
Copy link
Copy Markdown
Collaborator

rustbot commented Apr 20, 2026

BoxyUwU is currently at their maximum review capacity.
They may take a while to respond.

Copy link
Copy Markdown
Contributor Author

@popzxc popzxc left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some comments to assist with the review.

View changes since this review

Comment thread src/doc/unstable-book/src/language-features/generic-const-args.md
Comment thread src/doc/unstable-book/src/language-features/generic-const-args.md
Comment on lines +42 to +50
let mut i = 0;
while i < B::Y {
let mut j = 0;
while j < B::X {
out[i * B::X + j] = y[i].saturating_mul(x[j]);
j += 1;
}
i += 1;
}
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This body sort of shifts the attention from the things I wanted to highlight, but I thought that adding todo!() here would not feel genuine for readers.

@@ -0,0 +1,59 @@
# generic_const_items
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not directly related to other 3, but it 1. seems to be cross-referenced a lot (e.g. in UI tests), and 2. similar in spirit and might often be a thing that people actually want to have.

@@ -0,0 +1,110 @@
# min_generic_const_args

Enables the generic const args MVP.
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The feature description also states (only bare paths, not arbitrary computation), which feels out of date now -- right now more functionality seems to be supported, but I did not change any rust source code, as this feature is only about the documentation. Happy to change to whatever phrasing works better, both here and in unstable.rs if required.

Copy link
Copy Markdown
Member

@BoxyUwU BoxyUwU Apr 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

right now the things mGCA supports are:

  • paths to type const items (e.g. ::ASSOC)
  • tuple constructor calls (e.g. Some(N)
  • struct/enum variant expressions (e.g. Some { 0: N })
  • paths to const constructors (e.g. None::)
  • tuple expressions (e.g. (N,))
  • array expressions (e.g. [N, N])

Copy link
Copy Markdown
Member

@BoxyUwU BoxyUwU Apr 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe concise wording here is "Paths to type const items and constructors for ADTs and primitives"

@@ -0,0 +1,72 @@
# generic_const_exprs

Allows non-trivial generic constants which have to have wfness manually propagated to callers
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"wfness" might be an unfamiliar term for people outside of Rust compiler developers community, so it might not be suitable for public documentation; left it here because it's technically correct and used in unstable.rs.

Copy link
Copy Markdown
Member

@fmease fmease Apr 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

wfness = well-formedness; I would at least use the written-out form since that's an established term in linguistics that's searchable.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would say something like "which have to be shown to successfully evaluate to a value by being part of an item signature". i think even the fully written "well-formedness" is a bit too jargon

@rust-log-analyzer

This comment has been minimized.

@popzxc popzxc force-pushed the document-generic-const-features branch from 59f05a0 to b4886b2 Compare April 20, 2026 08:14

Related features: [generic_const_args], [generic_const_items].

[feature_background]: https://hackmd.io/OsVAAEgOS2ajDwxg44kN-A?view
Copy link
Copy Markdown
Member

@BoxyUwU BoxyUwU Apr 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think linking to a hackmd file is somewhat unfortunate 🤔 would you be willing to make a PR to the rust-lang/project-const-generics repo adding a documents/ directory and moving this document into there?

then we can link to a markdown file on github instead of a hackmd link

View changes since the review

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yup, will do slightly later!

@popzxc popzxc force-pushed the document-generic-const-features branch from b4886b2 to 73e44e8 Compare April 20, 2026 14:51
@rustbot rustbot added the T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. label Apr 20, 2026

Related features: [generic_const_args], [generic_const_items].

[feature_background]: https://github.com/rust-lang/project-const-generics/blob/main/documents/min_const_generics_plan.md
Copy link
Copy Markdown
Contributor Author

@popzxc popzxc Apr 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Comment thread src/doc/unstable-book/src/language-features/generic-const-items.md Outdated
Comment thread src/doc/unstable-book/src/language-features/generic-const-items.md Outdated
@rust-log-analyzer

This comment has been minimized.

Co-authored-by: León Orell Valerian Liehr <me@fmease.dev>
@popzxc popzxc force-pushed the document-generic-const-features branch from 656bb20 to c4eb1bf Compare April 23, 2026 05:08
@popzxc
Copy link
Copy Markdown
Contributor Author

popzxc commented Apr 28, 2026

@BoxyUwU is there anything else that needs to be done either in rust-lang/project-const-generics#110 or this PR?

@BoxyUwU
Copy link
Copy Markdown
Member

BoxyUwU commented May 1, 2026

left a comment on the other PR, this should be good to go once that's merged :)

@BoxyUwU
Copy link
Copy Markdown
Member

BoxyUwU commented May 1, 2026

@rustbot author

@rustbot rustbot added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels May 1, 2026
@rustbot
Copy link
Copy Markdown
Collaborator

rustbot commented May 1, 2026

Reminder, once the PR becomes ready for a review, use @rustbot ready.

@popzxc
Copy link
Copy Markdown
Contributor Author

popzxc commented May 4, 2026

@rustbot ready

This PR links the markdown file and the PR is merged, so should be good to go.
Also opened rust-lang/project-const-generics#112 to fix the book deployment.

@rustbot rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels May 4, 2026
@BoxyUwU
Copy link
Copy Markdown
Member

BoxyUwU commented May 4, 2026

@bors r+ rollup

@rust-bors
Copy link
Copy Markdown
Contributor

rust-bors Bot commented May 4, 2026

📌 Commit c4eb1bf has been approved by BoxyUwU

It is now in the queue for this repository.

@rust-bors rust-bors Bot added the S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. label May 4, 2026
@rust-bors rust-bors Bot removed the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label May 4, 2026
jhpratt added a commit to jhpratt/rust that referenced this pull request May 4, 2026
…ures, r=BoxyUwU

docs(unstable-book): Document const generics features

Relevant tracking issues: rust-lang#113521 rust-lang#132980 rust-lang#76560 rust-lang#151972

## What

Adds a high-level overview of 4 unstable features related to const generic exprs.

## Why

While trying to learn about the current state of const generic exprs, I found it a bit too hard due to lack of documentation -- had to read through a bunch of tracking issues & look for PRs/examples in the repo just to understand what the feature is about.

Moreover, given that there is a bunch of features with similarly-looking names, it was even more confusing. For that purpose, I also added cross-referencing across (directly or logically) related features.

As a result, I decided to add some more context to the unstable book, so that new readers have an easier time than I had.

## Caveats

I understand that the features are incomplete/experimental, so the docs are at risk of becoming stale, but the book entrypoint already has [a corresponding warning](https://doc.rust-lang.org/unstable-book/), so I guess it should be fine.

Also, given that I did research myself, the examples provided might be not the best to showcase the feature -- happy to provide better examples, if you have suggestions. The examples provided are what "made the feature make sense" to me as an outsider, so there is a chance that they will be good for other external readers too, though.

LLM use disclosue: an LLM was used for self-review only; research, coming up with examples, and writing is mine. Issues reported by LLM were fixed manually too.

r? @BoxyUwU
@rust-bors
Copy link
Copy Markdown
Contributor

rust-bors Bot commented May 4, 2026

⌛ Testing commit c4eb1bf with merge 1fac9f8...

Workflow: https://github.com/rust-lang/rust/actions/runs/25319609277

rust-bors Bot pushed a commit that referenced this pull request May 4, 2026
…yUwU

docs(unstable-book): Document const generics features



Relevant tracking issues: #113521 #132980 #76560 #151972

## What

Adds a high-level overview of 4 unstable features related to const generic exprs.

## Why

While trying to learn about the current state of const generic exprs, I found it a bit too hard due to lack of documentation -- had to read through a bunch of tracking issues & look for PRs/examples in the repo just to understand what the feature is about.

Moreover, given that there is a bunch of features with similarly-looking names, it was even more confusing. For that purpose, I also added cross-referencing across (directly or logically) related features.

As a result, I decided to add some more context to the unstable book, so that new readers have an easier time than I had.

## Caveats

I understand that the features are incomplete/experimental, so the docs are at risk of becoming stale, but the book entrypoint already has [a corresponding warning](https://doc.rust-lang.org/unstable-book/), so I guess it should be fine.

Also, given that I did research myself, the examples provided might be not the best to showcase the feature -- happy to provide better examples, if you have suggestions. The examples provided are what "made the feature make sense" to me as an outsider, so there is a chance that they will be good for other external readers too, though.

LLM use disclosue: an LLM was used for self-review only; research, coming up with examples, and writing is mine. Issues reported by LLM were fixed manually too.

r? @BoxyUwU
@jhpratt
Copy link
Copy Markdown
Member

jhpratt commented May 4, 2026

@bors yield

For encompassing rollup

@rust-bors
Copy link
Copy Markdown
Contributor

rust-bors Bot commented May 4, 2026

Auto build was cancelled. Cancelled workflows:

The next pull request likely to be tested is #156140.

rust-bors Bot pushed a commit that referenced this pull request May 4, 2026
Rollup of 6 pull requests

Successful merges:

 - #155543 (docs(unstable-book): Document const generics features)
 - #156043 (c-variadic: gate `va_arg` on `c_variadic_experimental_arch`)
 - #156082 (Move tests associated types)
 - #156092 (Clean up `TyCtxt::needs_crate_hash` usage and rename it to `needs_hir_hash`.)
 - #156104 (Relax `T: Sized` bound on `try_as_dyn` / `try_as_dyn_mut`)
 - #156128 (.mailmap: prefer matching just based on commit emails)
JonathanBrouwer added a commit to JonathanBrouwer/rust that referenced this pull request May 4, 2026
…ures, r=BoxyUwU

docs(unstable-book): Document const generics features

Relevant tracking issues: rust-lang#113521 rust-lang#132980 rust-lang#76560 rust-lang#151972

## What

Adds a high-level overview of 4 unstable features related to const generic exprs.

## Why

While trying to learn about the current state of const generic exprs, I found it a bit too hard due to lack of documentation -- had to read through a bunch of tracking issues & look for PRs/examples in the repo just to understand what the feature is about.

Moreover, given that there is a bunch of features with similarly-looking names, it was even more confusing. For that purpose, I also added cross-referencing across (directly or logically) related features.

As a result, I decided to add some more context to the unstable book, so that new readers have an easier time than I had.

## Caveats

I understand that the features are incomplete/experimental, so the docs are at risk of becoming stale, but the book entrypoint already has [a corresponding warning](https://doc.rust-lang.org/unstable-book/), so I guess it should be fine.

Also, given that I did research myself, the examples provided might be not the best to showcase the feature -- happy to provide better examples, if you have suggestions. The examples provided are what "made the feature make sense" to me as an outsider, so there is a chance that they will be good for other external readers too, though.

LLM use disclosue: an LLM was used for self-review only; research, coming up with examples, and writing is mine. Issues reported by LLM were fixed manually too.

r? @BoxyUwU
JonathanBrouwer added a commit to JonathanBrouwer/rust that referenced this pull request May 4, 2026
…ures, r=BoxyUwU

docs(unstable-book): Document const generics features

Relevant tracking issues: rust-lang#113521 rust-lang#132980 rust-lang#76560 rust-lang#151972

## What

Adds a high-level overview of 4 unstable features related to const generic exprs.

## Why

While trying to learn about the current state of const generic exprs, I found it a bit too hard due to lack of documentation -- had to read through a bunch of tracking issues & look for PRs/examples in the repo just to understand what the feature is about.

Moreover, given that there is a bunch of features with similarly-looking names, it was even more confusing. For that purpose, I also added cross-referencing across (directly or logically) related features.

As a result, I decided to add some more context to the unstable book, so that new readers have an easier time than I had.

## Caveats

I understand that the features are incomplete/experimental, so the docs are at risk of becoming stale, but the book entrypoint already has [a corresponding warning](https://doc.rust-lang.org/unstable-book/), so I guess it should be fine.

Also, given that I did research myself, the examples provided might be not the best to showcase the feature -- happy to provide better examples, if you have suggestions. The examples provided are what "made the feature make sense" to me as an outsider, so there is a chance that they will be good for other external readers too, though.

LLM use disclosue: an LLM was used for self-review only; research, coming up with examples, and writing is mine. Issues reported by LLM were fixed manually too.

r? @BoxyUwU
rust-bors Bot pushed a commit that referenced this pull request May 4, 2026
…uwer

Rollup of 10 pull requests

Successful merges:

 - #155848 ([doc]: Revert `core::io::ErrorKind` doc changes)
 - #155855 (Remove unnecessary `get_unchecked`)
 - #156062 (Added command-line argument support for `wasm32-wali-linux-musl`)
 - #155543 (docs(unstable-book): Document const generics features)
 - #156043 (c-variadic: gate `va_arg` on `c_variadic_experimental_arch`)
 - #156082 (Move tests associated types)
 - #156092 (Clean up `TyCtxt::needs_crate_hash` usage and rename it to `needs_hir_hash`.)
 - #156104 (Relax `T: Sized` bound on `try_as_dyn` / `try_as_dyn_mut`)
 - #156128 (.mailmap: prefer matching just based on commit emails)
 - #156135 (Remove most uses of def_id_to_node_id)
JonathanBrouwer added a commit to JonathanBrouwer/rust that referenced this pull request May 4, 2026
…ures, r=BoxyUwU

docs(unstable-book): Document const generics features

Relevant tracking issues: rust-lang#113521 rust-lang#132980 rust-lang#76560 rust-lang#151972

## What

Adds a high-level overview of 4 unstable features related to const generic exprs.

## Why

While trying to learn about the current state of const generic exprs, I found it a bit too hard due to lack of documentation -- had to read through a bunch of tracking issues & look for PRs/examples in the repo just to understand what the feature is about.

Moreover, given that there is a bunch of features with similarly-looking names, it was even more confusing. For that purpose, I also added cross-referencing across (directly or logically) related features.

As a result, I decided to add some more context to the unstable book, so that new readers have an easier time than I had.

## Caveats

I understand that the features are incomplete/experimental, so the docs are at risk of becoming stale, but the book entrypoint already has [a corresponding warning](https://doc.rust-lang.org/unstable-book/), so I guess it should be fine.

Also, given that I did research myself, the examples provided might be not the best to showcase the feature -- happy to provide better examples, if you have suggestions. The examples provided are what "made the feature make sense" to me as an outsider, so there is a chance that they will be good for other external readers too, though.

LLM use disclosue: an LLM was used for self-review only; research, coming up with examples, and writing is mine. Issues reported by LLM were fixed manually too.

r? @BoxyUwU
rust-bors Bot pushed a commit that referenced this pull request May 4, 2026
…uwer

Rollup of 10 pull requests

Successful merges:

 - #155848 ([doc]: Revert `core::io::ErrorKind` doc changes)
 - #155855 (Remove unnecessary `get_unchecked`)
 - #155543 (docs(unstable-book): Document const generics features)
 - #155962 (`rustc`: `target_features`: allow for `cfg`-only stable `target_features`)
 - #156043 (c-variadic: gate `va_arg` on `c_variadic_experimental_arch`)
 - #156082 (Move tests associated types)
 - #156092 (Clean up `TyCtxt::needs_crate_hash` usage and rename it to `needs_hir_hash`.)
 - #156104 (Relax `T: Sized` bound on `try_as_dyn` / `try_as_dyn_mut`)
 - #156128 (.mailmap: prefer matching just based on commit emails)
 - #156135 (Remove most uses of def_id_to_node_id)
JonathanBrouwer added a commit to JonathanBrouwer/rust that referenced this pull request May 4, 2026
…ures, r=BoxyUwU

docs(unstable-book): Document const generics features

Relevant tracking issues: rust-lang#113521 rust-lang#132980 rust-lang#76560 rust-lang#151972

## What

Adds a high-level overview of 4 unstable features related to const generic exprs.

## Why

While trying to learn about the current state of const generic exprs, I found it a bit too hard due to lack of documentation -- had to read through a bunch of tracking issues & look for PRs/examples in the repo just to understand what the feature is about.

Moreover, given that there is a bunch of features with similarly-looking names, it was even more confusing. For that purpose, I also added cross-referencing across (directly or logically) related features.

As a result, I decided to add some more context to the unstable book, so that new readers have an easier time than I had.

## Caveats

I understand that the features are incomplete/experimental, so the docs are at risk of becoming stale, but the book entrypoint already has [a corresponding warning](https://doc.rust-lang.org/unstable-book/), so I guess it should be fine.

Also, given that I did research myself, the examples provided might be not the best to showcase the feature -- happy to provide better examples, if you have suggestions. The examples provided are what "made the feature make sense" to me as an outsider, so there is a chance that they will be good for other external readers too, though.

LLM use disclosue: an LLM was used for self-review only; research, coming up with examples, and writing is mine. Issues reported by LLM were fixed manually too.

r? @BoxyUwU
rust-bors Bot pushed a commit that referenced this pull request May 4, 2026
…uwer

Rollup of 12 pull requests

Successful merges:

 - #155848 ([doc]: Revert `core::io::ErrorKind` doc changes)
 - #155855 (Remove unnecessary `get_unchecked`)
 - #155543 (docs(unstable-book): Document const generics features)
 - #155962 (`rustc`: `target_features`: allow for `cfg`-only stable `target_features`)
 - #156043 (c-variadic: gate `va_arg` on `c_variadic_experimental_arch`)
 - #156082 (Move tests associated types)
 - #156092 (Clean up `TyCtxt::needs_crate_hash` usage and rename it to `needs_hir_hash`.)
 - #156103 (Fix E0040 suggestion for explicit `Drop::drop` UFCS calls)
 - #156104 (Relax `T: Sized` bound on `try_as_dyn` / `try_as_dyn_mut`)
 - #156128 (.mailmap: prefer matching just based on commit emails)
 - #156135 (Remove most uses of def_id_to_node_id)
 - #156152 (Update books)
GuillaumeGomez added a commit to GuillaumeGomez/rust that referenced this pull request May 5, 2026
…ures, r=BoxyUwU

docs(unstable-book): Document const generics features

Relevant tracking issues: rust-lang#113521 rust-lang#132980 rust-lang#76560 rust-lang#151972

## What

Adds a high-level overview of 4 unstable features related to const generic exprs.

## Why

While trying to learn about the current state of const generic exprs, I found it a bit too hard due to lack of documentation -- had to read through a bunch of tracking issues & look for PRs/examples in the repo just to understand what the feature is about.

Moreover, given that there is a bunch of features with similarly-looking names, it was even more confusing. For that purpose, I also added cross-referencing across (directly or logically) related features.

As a result, I decided to add some more context to the unstable book, so that new readers have an easier time than I had.

## Caveats

I understand that the features are incomplete/experimental, so the docs are at risk of becoming stale, but the book entrypoint already has [a corresponding warning](https://doc.rust-lang.org/unstable-book/), so I guess it should be fine.

Also, given that I did research myself, the examples provided might be not the best to showcase the feature -- happy to provide better examples, if you have suggestions. The examples provided are what "made the feature make sense" to me as an outsider, so there is a chance that they will be good for other external readers too, though.

LLM use disclosue: an LLM was used for self-review only; research, coming up with examples, and writing is mine. Issues reported by LLM were fixed manually too.

r? @BoxyUwU
rust-bors Bot pushed a commit that referenced this pull request May 5, 2026
Rollup of 16 pull requests

Successful merges:

 - #155848 ([doc]: Revert `core::io::ErrorKind` doc changes)
 - #155855 (Remove unnecessary `get_unchecked`)
 - #155543 (docs(unstable-book): Document const generics features)
 - #155962 (`rustc`: `target_features`: allow for `cfg`-only stable `target_features`)
 - #156043 (c-variadic: gate `va_arg` on `c_variadic_experimental_arch`)
 - #156082 (Move tests associated types)
 - #156087 (Improve `&pin` reference-pattern suggestions)
 - #156092 (Clean up `TyCtxt::needs_crate_hash` usage and rename it to `needs_hir_hash`.)
 - #156103 (Fix E0040 suggestion for explicit `Drop::drop` UFCS calls)
 - #156104 (Relax `T: Sized` bound on `try_as_dyn` / `try_as_dyn_mut`)
 - #156122 (Add a `doc_cfg` regression test to ensure foreign types impls are working as expected)
 - #156128 (.mailmap: prefer matching just based on commit emails)
 - #156135 (Remove most uses of def_id_to_node_id)
 - #156152 (Update books)
 - #156154 (tests: mark import UI tests as check-pass)
 - #156162 (Update `browser-ui-test` version to `0.23.5`)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. T-compiler Relevant to the compiler team, which will review and decide on the PR/issue.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants