Skip to content

rewrite never type documentation - #158370

Open
WaffleLapkin wants to merge 1 commit into
rust-lang:mainfrom
WaffleLapkin:never-scratch-docs
Open

rewrite never type documentation#158370
WaffleLapkin wants to merge 1 commit into
rust-lang:mainfrom
WaffleLapkin:never-scratch-docs

Conversation

@WaffleLapkin

@WaffleLapkin WaffleLapkin commented Jun 24, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

View all comments

With the never type stabilization in #155499, I think the never type documentation needs be improved, as the status quo is not the best ^^'

@rustbot rustbot added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Jun 24, 2026
@WaffleLapkin WaffleLapkin added the F-never_type `#![feature(never_type)]` label Jun 24, 2026
This was referenced Jun 24, 2026
Closed
Merged
@WaffleLapkin WaffleLapkin added S-blocked Status: Blocked on something else such as an RFC or other implementation work. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Jun 24, 2026
kpreid
kpreid reviewed Jun 25, 2026
View reviewed changes

@kpreid kpreid left a comment •
edited by rustbot
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I saw some typos, so here’s a batch of copyediting suggestions (also some for jargon clarification). Feel free to ignore these if not useful.

View changes since this review

Comment thread library/core/src/primitive_docs.rs Outdated
Comment thread library/core/src/primitive_docs.rs Outdated
Comment thread library/core/src/primitive_docs.rs Outdated
Comment thread library/core/src/primitive_docs.rs Outdated
Comment thread library/core/src/primitive_docs.rs Outdated
Comment thread library/core/src/primitive_docs.rs Outdated
@traviscross traviscross self-assigned this Jun 25, 2026
@traviscross traviscross added T-lang Relevant to the language team T-lang-docs Relevant to the lang-docs team. labels Jun 25, 2026
mkrasnitski
mkrasnitski reviewed Jun 27, 2026
View reviewed changes

@mkrasnitski mkrasnitski left a comment •
edited by rustbot
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Due to the slightly messy diff, I ended up splitting my review up into many small comments, so apologies for the large number of them. Most are copy-edits, with a couple small content changes here and there. Feel free to use them or not as you see fit.

View changes since this review

Comment thread library/core/src/primitive_docs.rs
Comment on lines +67 to +68
/// `!` is the canonical uninhabited type. `!` represents the type of diverging computations --
/// computations which never resolve to any value.

@mkrasnitski mkrasnitski Jun 26, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
/// `!` is the canonical uninhabited type. `!` represents the type of diverging computations --
/// computations which never resolve to any value.
/// `!` represents the type of diverging computations -- computations which never resolve to any
/// value. It is the canonical uninhabited type.

Comment thread library/core/src/primitive_docs.rs Outdated
Comment thread library/core/src/primitive_docs.rs Outdated
Comment thread library/core/src/primitive_docs.rs
Comment on lines +77 to +78
/// Similarly, [`return`], [`break`], [`continue`], [`become`], and infinite [`loop`] expressions
/// all have type `!`, as the code following them is unreachable.

@mkrasnitski mkrasnitski Jun 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Should become be included here if it is still unstable?

@WaffleLapkin WaffleLapkin Jun 30, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Why not?

Comment thread library/core/src/primitive_docs.rs Outdated
Comment thread library/core/src/primitive_docs.rs
Comment thread library/core/src/primitive_docs.rs Outdated
Comment thread library/core/src/primitive_docs.rs Outdated
Comment thread library/core/src/primitive_docs.rs Outdated
Comment thread library/core/src/primitive_docs.rs Outdated
WaffleLapkin
WaffleLapkin commented Jun 30, 2026
View reviewed changes
Comment thread library/core/src/primitive_docs.rs Outdated
WaffleLapkin
WaffleLapkin commented Jun 30, 2026
View reviewed changes

@WaffleLapkin WaffleLapkin left a comment •
edited by rustbot
Loading

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

@mkrasnitski thanks for your suggestions!

View changes since this review

Comment thread library/core/src/primitive_docs.rs Outdated
Comment thread library/core/src/primitive_docs.rs Outdated
Comment thread library/core/src/primitive_docs.rs Outdated
@rust-bors

This comment has been minimized.

Sign in to view
JonathanBrouwer added a commit to JonathanBrouwer/rust that referenced this pull request Aug 24, 2026
@JonathanBrouwer
Rollup merge of rust-lang#155499 - WaffleLapkin:stabilize-never-type,…
7a22c83 
… r=JonathanBrouwer

stabilize never type

### This PR

- stabilizes the [never type](https://doc.rust-lang.org/stable/std/primitive.never.html) (aka `!`) (!!!)
- sets the [never type fallback](https://doc.rust-lang.org/edition-guide/rust-2024/never-type-fallback.html) to `!` on all editions (breaking change, see [crater report analysis](rust-lang#155499 (comment)) and [refresher on never type fallback](rust-lang#155499 (comment)))
- makes `Infallible` an alias to `!`
- removes `dependency_on_unit_never_type_fallback` lint (there is no more never type fallback to `()` so this lint can't be triggered)

### Cat
<img width="1024" height="683" alt="52270233795_5979a3174d_b" src="https://github.com/user-attachments/assets/f6b4737e-32ef-4c33-86b2-76b81673cf20" />

### Tracking

- rust-lang#35121
- rust-lang#148922

### FCPs

- rust-lang#123508 (comment) (stabilization plan, T-lang)
- rust-lang#155499 (comment) (never type stabilization modulo bugs, T-lang)
- rust-lang#155924 (comment) (make `Infallible = !`, T-libs)

### Related changes

- Lint bump: rust-lang#141937
- Rust 2024 edition change:
   - rust-lang#123748
   - rust-lang#123508
- Various changes to lessen the effect of the breaking changes:
   - rust-lang#157820
   - rust-lang#156047
   - rust-lang#160705
- Never type documentation changes: rust-lang#158370 (blocked on this pr)

### Experiments

- Fallback change and never type stabilization:
  - Run: rust-lang#155499 (comment)
  - Analysis: rust-lang#155499 (comment)
  - Status of backports: rust-lang#155499 (comment)
- Fallback change, never type stabilization and making `Infallible = !`: rust-lang#155500
- Fallback change, never type stabilization, making `Infallible = !`, and removing reservation impl: rust-lang#155501
- Never type stabilization and `Infallible = !` change, _without_ fallback change: rust-lang#155657

---

Closes rust-lang#35121
Closes rust-lang#148922
JonathanBrouwer added a commit to JonathanBrouwer/rust that referenced this pull request Aug 24, 2026
@JonathanBrouwer
Rollup merge of rust-lang#155499 - WaffleLapkin:stabilize-never-type,…
e78f5c8 
… r=JonathanBrouwer

stabilize never type

### This PR

- stabilizes the [never type](https://doc.rust-lang.org/stable/std/primitive.never.html) (aka `!`) (!!!)
- sets the [never type fallback](https://doc.rust-lang.org/edition-guide/rust-2024/never-type-fallback.html) to `!` on all editions (breaking change, see [crater report analysis](rust-lang#155499 (comment)) and [refresher on never type fallback](rust-lang#155499 (comment)))
- makes `Infallible` an alias to `!`
- removes `dependency_on_unit_never_type_fallback` lint (there is no more never type fallback to `()` so this lint can't be triggered)

### Cat
<img width="1024" height="683" alt="52270233795_5979a3174d_b" src="https://github.com/user-attachments/assets/f6b4737e-32ef-4c33-86b2-76b81673cf20" />

### Tracking

- rust-lang#35121
- rust-lang#148922

### FCPs

- rust-lang#123508 (comment) (stabilization plan, T-lang)
- rust-lang#155499 (comment) (never type stabilization modulo bugs, T-lang)
- rust-lang#155924 (comment) (make `Infallible = !`, T-libs)

### Related changes

- Lint bump: rust-lang#141937
- Rust 2024 edition change:
   - rust-lang#123748
   - rust-lang#123508
- Various changes to lessen the effect of the breaking changes:
   - rust-lang#157820
   - rust-lang#156047
   - rust-lang#160705
- Never type documentation changes: rust-lang#158370 (blocked on this pr)

### Experiments

- Fallback change and never type stabilization:
  - Run: rust-lang#155499 (comment)
  - Analysis: rust-lang#155499 (comment)
  - Status of backports: rust-lang#155499 (comment)
- Fallback change, never type stabilization and making `Infallible = !`: rust-lang#155500
- Fallback change, never type stabilization, making `Infallible = !`, and removing reservation impl: rust-lang#155501
- Never type stabilization and `Infallible = !` change, _without_ fallback change: rust-lang#155657

---

Closes rust-lang#35121
Closes rust-lang#148922
JonathanBrouwer added a commit to JonathanBrouwer/rust that referenced this pull request Aug 24, 2026
@JonathanBrouwer
Rollup merge of rust-lang#155499 - WaffleLapkin:stabilize-never-type,…
e0afd03 
… r=JonathanBrouwer

stabilize never type

### This PR

- stabilizes the [never type](https://doc.rust-lang.org/stable/std/primitive.never.html) (aka `!`) (!!!)
- sets the [never type fallback](https://doc.rust-lang.org/edition-guide/rust-2024/never-type-fallback.html) to `!` on all editions (breaking change, see [crater report analysis](rust-lang#155499 (comment)) and [refresher on never type fallback](rust-lang#155499 (comment)))
- makes `Infallible` an alias to `!`
- removes `dependency_on_unit_never_type_fallback` lint (there is no more never type fallback to `()` so this lint can't be triggered)

### Cat
<img width="1024" height="683" alt="52270233795_5979a3174d_b" src="https://github.com/user-attachments/assets/f6b4737e-32ef-4c33-86b2-76b81673cf20" />

### Tracking

- rust-lang#35121
- rust-lang#148922

### FCPs

- rust-lang#123508 (comment) (stabilization plan, T-lang)
- rust-lang#155499 (comment) (never type stabilization modulo bugs, T-lang)
- rust-lang#155924 (comment) (make `Infallible = !`, T-libs)

### Related changes

- Lint bump: rust-lang#141937
- Rust 2024 edition change:
   - rust-lang#123748
   - rust-lang#123508
- Various changes to lessen the effect of the breaking changes:
   - rust-lang#157820
   - rust-lang#156047
   - rust-lang#160705
- Never type documentation changes: rust-lang#158370 (blocked on this pr)

### Experiments

- Fallback change and never type stabilization:
  - Run: rust-lang#155499 (comment)
  - Analysis: rust-lang#155499 (comment)
  - Status of backports: rust-lang#155499 (comment)
- Fallback change, never type stabilization and making `Infallible = !`: rust-lang#155500
- Fallback change, never type stabilization, making `Infallible = !`, and removing reservation impl: rust-lang#155501
- Never type stabilization and `Infallible = !` change, _without_ fallback change: rust-lang#155657

---

Closes rust-lang#35121
Closes rust-lang#148922
rust-bors Bot pushed a commit that referenced this pull request Aug 24, 2026
@bors
Auto merge of #155499 - WaffleLapkin:stabilize-never-type, r=Jonathan…
4b53dd4 
…Brouwer

stabilize never type



### This PR

- stabilizes the [never type](https://doc.rust-lang.org/stable/std/primitive.never.html) (aka `!`) (!!!)
- sets the [never type fallback](https://doc.rust-lang.org/edition-guide/rust-2024/never-type-fallback.html) to `!` on all editions (breaking change, see [crater report analysis](#155499 (comment)) and [refresher on never type fallback](#155499 (comment)))
- makes `Infallible` an alias to `!`
- removes `dependency_on_unit_never_type_fallback` lint (there is no more never type fallback to `()` so this lint can't be triggered)

### Cat
<img width="1024" height="683" alt="52270233795_5979a3174d_b" src="https://github.com/user-attachments/assets/f6b4737e-32ef-4c33-86b2-76b81673cf20" />

### Tracking

- #35121
- #148922

### FCPs

- #123508 (comment) (stabilization plan, T-lang)
- #155499 (comment) (never type stabilization modulo bugs, T-lang)
- #155924 (comment) (make `Infallible = !`, T-libs)

### Related changes

- Lint bump: #141937
- Rust 2024 edition change:
   - #123748
   - #123508
- Various changes to lessen the effect of the breaking changes:
   - #157820
   - #156047
   - #160705
- Never type documentation changes: #158370 (blocked on this pr)

### Experiments

- Fallback change and never type stabilization:
  - Run: #155499 (comment)
  - Analysis: #155499 (comment)
  - Status of backports: #155499 (comment)
- Fallback change, never type stabilization and making `Infallible = !`: #155500
- Fallback change, never type stabilization, making `Infallible = !`, and removing reservation impl: #155501
- Never type stabilization and `Infallible = !` change, _without_ fallback change: #155657

---

Closes #35121
Closes #148922
JonathanBrouwer added a commit to JonathanBrouwer/rust that referenced this pull request Aug 24, 2026
@JonathanBrouwer
Rollup merge of rust-lang#155499 - WaffleLapkin:stabilize-never-type,…
b76a5ca 
… r=JonathanBrouwer

stabilize never type

### This PR

- stabilizes the [never type](https://doc.rust-lang.org/stable/std/primitive.never.html) (aka `!`) (!!!)
- sets the [never type fallback](https://doc.rust-lang.org/edition-guide/rust-2024/never-type-fallback.html) to `!` on all editions (breaking change, see [crater report analysis](rust-lang#155499 (comment)) and [refresher on never type fallback](rust-lang#155499 (comment)))
- makes `Infallible` an alias to `!`
- removes `dependency_on_unit_never_type_fallback` lint (there is no more never type fallback to `()` so this lint can't be triggered)

### Cat
<img width="1024" height="683" alt="52270233795_5979a3174d_b" src="https://github.com/user-attachments/assets/f6b4737e-32ef-4c33-86b2-76b81673cf20" />

### Tracking

- rust-lang#35121
- rust-lang#148922

### FCPs

- rust-lang#123508 (comment) (stabilization plan, T-lang)
- rust-lang#155499 (comment) (never type stabilization modulo bugs, T-lang)
- rust-lang#155924 (comment) (make `Infallible = !`, T-libs)

### Related changes

- Lint bump: rust-lang#141937
- Rust 2024 edition change:
   - rust-lang#123748
   - rust-lang#123508
- Various changes to lessen the effect of the breaking changes:
   - rust-lang#157820
   - rust-lang#156047
   - rust-lang#160705
- Never type documentation changes: rust-lang#158370 (blocked on this pr)

### Experiments

- Fallback change and never type stabilization:
  - Run: rust-lang#155499 (comment)
  - Analysis: rust-lang#155499 (comment)
  - Status of backports: rust-lang#155499 (comment)
- Fallback change, never type stabilization and making `Infallible = !`: rust-lang#155500
- Fallback change, never type stabilization, making `Infallible = !`, and removing reservation impl: rust-lang#155501
- Never type stabilization and `Infallible = !` change, _without_ fallback change: rust-lang#155657

---

Closes rust-lang#35121
Closes rust-lang#148922
rust-bors Bot pushed a commit that referenced this pull request Aug 24, 2026
@bors
Auto merge of #155499 - WaffleLapkin:stabilize-never-type, r=Jonathan…
e776960 
…Brouwer

stabilize never type



### This PR

- stabilizes the [never type](https://doc.rust-lang.org/stable/std/primitive.never.html) (aka `!`) (!!!)
- sets the [never type fallback](https://doc.rust-lang.org/edition-guide/rust-2024/never-type-fallback.html) to `!` on all editions (breaking change, see [crater report analysis](#155499 (comment)) and [refresher on never type fallback](#155499 (comment)))
- makes `Infallible` an alias to `!`
- removes `dependency_on_unit_never_type_fallback` lint (there is no more never type fallback to `()` so this lint can't be triggered)

### Cat
<img width="1024" height="683" alt="52270233795_5979a3174d_b" src="https://github.com/user-attachments/assets/f6b4737e-32ef-4c33-86b2-76b81673cf20" />

### Tracking

- #35121
- #148922

### FCPs

- #123508 (comment) (stabilization plan, T-lang)
- #155499 (comment) (never type stabilization modulo bugs, T-lang)
- #155924 (comment) (make `Infallible = !`, T-libs)

### Related changes

- Lint bump: #141937
- Rust 2024 edition change:
   - #123748
   - #123508
- Various changes to lessen the effect of the breaking changes:
   - #157820
   - #156047
   - #160705
- Never type documentation changes: #158370 (blocked on this pr)

### Experiments

- Fallback change and never type stabilization:
  - Run: #155499 (comment)
  - Analysis: #155499 (comment)
  - Status of backports: #155499 (comment)
- Fallback change, never type stabilization and making `Infallible = !`: #155500
- Fallback change, never type stabilization, making `Infallible = !`, and removing reservation impl: #155501
- Never type stabilization and `Infallible = !` change, _without_ fallback change: #155657

---

Closes #35121
Closes #148922
@fmease fmease mentioned this pull request Aug 25, 2026
Closed
@WaffleLapkin
WaffleLapkin marked this pull request as ready for review August 25, 2026 08:57
@rustbot rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Aug 25, 2026
@rustbot

This comment has been minimized.

Sign in to view
pull Bot pushed a commit to xtqqczze/rust-lang-miri that referenced this pull request Aug 25, 2026
@bors
Auto merge of #155499 - WaffleLapkin:stabilize-never-type, r=Jonathan…
89242b0 
…Brouwer

stabilize never type



### This PR

- stabilizes the [never type](https://doc.rust-lang.org/stable/std/primitive.never.html) (aka `!`) (!!!)
- sets the [never type fallback](https://doc.rust-lang.org/edition-guide/rust-2024/never-type-fallback.html) to `!` on all editions (breaking change, see [crater report analysis](rust-lang/rust#155499 (comment)) and [refresher on never type fallback](rust-lang/rust#155499 (comment)))
- makes `Infallible` an alias to `!`
- removes `dependency_on_unit_never_type_fallback` lint (there is no more never type fallback to `()` so this lint can't be triggered)

### Cat
<img width="1024" height="683" alt="52270233795_5979a3174d_b" src="https://github.com/user-attachments/assets/f6b4737e-32ef-4c33-86b2-76b81673cf20" />

### Tracking

- rust-lang/rust#35121
- rust-lang/rust#148922

### FCPs

- rust-lang/rust#123508 (comment) (stabilization plan, T-lang)
- rust-lang/rust#155499 (comment) (never type stabilization modulo bugs, T-lang)
- rust-lang/rust#155924 (comment) (make `Infallible = !`, T-libs)

### Related changes

- Lint bump: rust-lang/rust#141937
- Rust 2024 edition change:
   - rust-lang/rust#123748
   - rust-lang/rust#123508
- Various changes to lessen the effect of the breaking changes:
   - rust-lang/rust#157820
   - rust-lang/rust#156047
   - rust-lang/rust#160705
- Never type documentation changes: rust-lang/rust#158370 (blocked on this pr)

### Experiments

- Fallback change and never type stabilization:
  - Run: rust-lang/rust#155499 (comment)
  - Analysis: rust-lang/rust#155499 (comment)
  - Status of backports: rust-lang/rust#155499 (comment)
- Fallback change, never type stabilization and making `Infallible = !`: rust-lang/rust#155500
- Fallback change, never type stabilization, making `Infallible = !`, and removing reservation impl: rust-lang/rust#155501
- Never type stabilization and `Infallible = !` change, _without_ fallback change: rust-lang/rust#155657

---

Closes rust-lang/rust#35121
Closes rust-lang/rust#148922
@traviscross traviscross added the I-lang-docs-nominated Nominated for discussion during a lang-docs team meeting. label Aug 25, 2026
traviscross
traviscross approved these changes Aug 25, 2026
View reviewed changes
Comment thread library/core/src/primitive_docs.rs Outdated
Comment thread library/core/src/primitive_docs.rs Outdated
Comment thread library/core/src/primitive_docs.rs Outdated
Comment thread library/core/src/primitive_docs.rs Outdated
@traviscross

traviscross commented Aug 25, 2026

Copy link
Copy Markdown
Contributor

This looks good to me. Thanks @WaffleLapkin. r=me after considering the nits, rebasing, and squashing.

@traviscross traviscross added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-blocked Status: Blocked on something else such as an RFC or other implementation work. S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Aug 25, 2026
@rustbot

rustbot commented Aug 26, 2026

Copy link
Copy Markdown
Collaborator

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

@JonathanBrouwer JonathanBrouwer self-assigned this Aug 26, 2026
JonathanBrouwer
JonathanBrouwer approved these changes Aug 26, 2026
View reviewed changes

@JonathanBrouwer JonathanBrouwer left a comment •
edited by rustbot
Loading

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.

@bors r=JonathanBrouwer,traviscross rollup

View changes since this review

@rust-bors

rust-bors Bot commented Aug 26, 2026

Copy link
Copy Markdown
Contributor

📌 Commit c68342d has been approved by JonathanBrouwer,traviscross

It is now in the queue for this repository.

@rust-bors rust-bors Bot added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Aug 26, 2026
JonathanBrouwer added a commit to JonathanBrouwer/rust that referenced this pull request Aug 26, 2026
@JonathanBrouwer
Rollup merge of rust-lang#158370 - WaffleLapkin:never-scratch-docs, r…
25fb365 
…=JonathanBrouwer,traviscross

rewrite never type documentation

With the never type stabilization in rust-lang#155499, I think the never type documentation needs be improved, as the status quo is not the best ^^'
@JonathanBrouwer JonathanBrouwer mentioned this pull request Aug 26, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@traviscross traviscross traviscross approved these changes
@JonathanBrouwer JonathanBrouwer JonathanBrouwer approved these changes
+4 more reviewers
@kpreid kpreid kpreid left review comments
@av-gal av-gal av-gal left review comments
@mkrasnitski mkrasnitski mkrasnitski left review comments
@poseidon-rises poseidon-rises poseidon-rises left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

@traviscross traviscross

@JonathanBrouwer JonathanBrouwer

Labels

F-never_type `#![feature(never_type)]` I-lang-docs-nominated Nominated for discussion during a lang-docs team meeting. S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. T-lang Relevant to the language team T-lang-docs Relevant to the lang-docs team. T-libs Relevant to the library team, which will review and decide on the PR/issue.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

8 participants

@WaffleLapkin @rustbot @traviscross @kpreid @JonathanBrouwer @av-gal @mkrasnitski @poseidon-rises