rewrite never type documentation by WaffleLapkin · Pull Request #158370 · rust-lang/rust

WaffleLapkin · 2026-06-24T17:39:15Z

With the never type stabilization approaching, I think the documentation could be improved a lot over the status quo ^^'

I intend to merge this after #155499. Split it off into a separate PR for ease of reviewing.

kpreid

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

mkrasnitski

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

mkrasnitski · 2026-06-26T15:49:42Z

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


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 the canonical uninhabited type.

mkrasnitski · 2026-06-26T15:50:33Z

+/// For example, the [`exit`] function is defined as returning `!`, to signify that it doesn't
+/// return normally and exits the process instead. Thus, any code following a call to [`exit`] is
+/// unreachable. ([`panic!`] works the same way.)


Suggested change

/// For example, the [`exit`] function is defined as returning `!`, to signify that it doesn't

/// return normally and exits the process instead. Thus, any code following a call to [`exit`] is

/// unreachable. ([`panic!`] works the same way.)

/// For example, the [`exit`] function is defined as returning `!`, to signify that it exits the

/// process instead of returning normally. Thus, any code following a call to [`exit`] is

/// unreachable. The [`panic!`] macro works the same way.

I think your suggestion is misleading here. returning ! doesn't signify that the function exits the process, only that it doesn't return. Now realizing, that my version kind-of struggles from the same issue...

How about the following?

For example, the exit function is defined as returning !, to signify that it doesn't return normally (as it exits the process instead).

mkrasnitski · 2026-06-26T15:51:01Z

+/// Similarly, [`return`], [`break`], [`continue`], [`become`], and infinite [`loop`] expressions
+/// all have type `!`, as the code following them is unreachable.


Should become be included here if it is still unstable?

mkrasnitski · 2026-06-27T06:15:43Z

+/// This is because `impl Trait` is not a specific type in and of itself, but instead a marker that
+/// the return type of the function is hidden and the only thing that can be assumed by the caller
+/// is that whatever the type is, it implements `Trait`.


Suggested change

/// This is because `impl Trait` is not a specific type in and of itself, but instead a marker that

/// the return type of the function is hidden and the only thing that can be assumed by the caller

/// is that whatever the type is, it implements `Trait`.

/// Here, never-to-any coercion fails because `impl Trait` is not itself a concrete type, but rather

/// a way to tell the compiler that a function's return type is hidden, and the only thing which can

/// be assumed about this type is that it implements `Trait`.

Never-to-any doesn't fail here; the failure is that the hidden type doesn't implement the correct trait.

I rewrote "a specific type in and of itself" though.

mkrasnitski · 2026-06-27T06:16:18Z

+/// In case of using `todo!()` the hidden return type is inferred to be `!`, which may not
+/// implement the trait.


Suggested change

/// In case of using `todo!()` the hidden return type is inferred to be `!`, which may not

/// implement the trait.

/// The compiler then attempts to choose such a concrete type, but is unable to do so. In this case,

/// we abandon the coercion and fall back to just the never type itself, which will fail to compile

/// if `!` does not implement `Trait`.

I think fallback should be explicitly mentioned here.

The compiler then attempts to choose such a concrete type, but is unable to do so.

This is not true; the compiler chooses ! here.

I think mentioning fallback here only makes it more confusing...

Co-authored-by: Kevin Reid <kpreid@switchb.org>

Co-authored-by: Kevin Reid <kpreid@switchb.org> Co-authored-by: Michael Krasnitski <42564254+mkrasnitski@users.noreply.github.com> Co-authored-by: waffle <waffle.lapkin@gmail.com>

Co-authored-by: Michael Krasnitski <42564254+mkrasnitski@users.noreply.github.com>

WaffleLapkin

@mkrasnitski thanks for your suggestions!

View changes since this review

WaffleLapkin · 2026-06-30T08:57:00Z

+/// This is because `impl Trait` is not a specific type in and of itself, but instead a marker that
+/// the return type of the function is hidden and the only thing that can be assumed by the caller
+/// is that whatever the type is, it implements `Trait`.


Never-to-any doesn't fail here; the failure is that the hidden type doesn't implement the correct trait.

I rewrote "a specific type in and of itself" though.

WaffleLapkin · 2026-06-30T09:00:05Z

+/// At first glance there is no reason to implement any traits for `!`. Most traits take a value
+/// of `Self` as an argument in methods, so you won't be able to call them anyway.


Incorporated this into my last commit.

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 added the F-never_type `#![feature(never_type)]` label Jun 24, 2026

This was referenced Jun 24, 2026

Update wording for ! (never type) docs #157823

Open

stabilize never type #155499

Open

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 reviewed Jun 25, 2026

View reviewed changes

traviscross self-assigned this Jun 25, 2026

traviscross added T-lang Relevant to the language team T-lang-docs Relevant to the lang-docs team. labels Jun 25, 2026

mkrasnitski reviewed Jun 27, 2026

View reviewed changes

WaffleLapkin commented Jun 30, 2026

View reviewed changes

Comment thread library/core/src/primitive_docs.rs Outdated

WaffleLapkin and others added 4 commits June 30, 2026 11:06

rewrite never type documentation

bc6c619

Apply suggestions from code review

a6ff5ac

Co-authored-by: Kevin Reid <kpreid@switchb.org>

Apply suggestions from code review

03e0b67

Co-authored-by: Kevin Reid <kpreid@switchb.org> Co-authored-by: Michael Krasnitski <42564254+mkrasnitski@users.noreply.github.com> Co-authored-by: waffle <waffle.lapkin@gmail.com>

partially apply review comments & do some edits

cd5b51c

Co-authored-by: Michael Krasnitski <42564254+mkrasnitski@users.noreply.github.com>

WaffleLapkin force-pushed the never-scratch-docs branch from f2dc120 to cd5b51c Compare June 30, 2026 09:10

WaffleLapkin commented Jun 30, 2026

View reviewed changes

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

		/// Similarly, [`return`], [`break`], [`continue`], [`become`], and infinite [`loop`] expressions
		/// all have type `!`, as the code following them is unreachable.

		/// In case of using `todo!()` the hidden return type is inferred to be `!`, which may not
		/// implement the trait.

-/// In case of using `todo!()` the hidden return type is inferred to be `!`, which may not
-/// implement the trait.
+/// The compiler then attempts to choose such a concrete type, but is unable to do so. In this case,
+/// we abandon the coercion and fall back to just the never type itself, which will fail to compile
+/// if `!` does not implement `Trait`.

		/// At first glance there is no reason to implement any traits for `!`. Most traits take a value
		/// of `Self` as an argument in methods, so you won't be able to call them anyway.

Uh oh!

Uh oh!

Conversation

WaffleLapkin commented Jun 24, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kpreid left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mkrasnitski left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

WaffleLapkin left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

WaffleLapkin commented Jun 24, 2026 •

edited by rustbot

Loading

kpreid left a comment •

edited by rustbot

Loading

mkrasnitski left a comment •

edited by rustbot

Loading

WaffleLapkin left a comment •

edited by rustbot

Loading