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).

That works 👍

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.

True, there is no actual coercion attempt happening here. What do you think of:

This is because impl Trait is not 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 the hidden
type is that it implements Trait.

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...

You're right, I kind of forgot that ! is a concrete type. How about the following (which merges the sentence after as well):

In this case, the hidden return type is inferred to be !, which does not implement Iterator.
A fix to this is to explicitly cast ! to a type which implements the trait:

mkrasnitski · 2026-06-27T06:21:49Z

+/// // Enum with no variants is an example of an uninhabited type
+/// enum Void {}


Suggested change

/// // Enum with no variants is an example of an uninhabited type

/// enum Void {}

/// // An enum with no variants is an example of an uninhabited type

/// enum Void {}

Probably this should be moved up above the definition of Onomatopoeias

Probably this should be moved up above the definition of Onomatopoeias

Why?

When reading the example code for the first time, seeing Mjau(Void) and a mention of "other uninhabited types" without first seeing that Void is user-defined in this example could imply that it's some existing built-in type. Moving the definition of Void up top clears that up.

Also, the sentence right before the example mentions that there are other uninhabited types besides !, and this also immediately answers the question of what exactly those might be.

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`.

		/// // Enum with no variants is an example of an uninhabited type
		/// enum Void {}

		/// 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!

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!

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!

Choose a reason for hiding this comment

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