Document nonzero invariant on NonZero::unchecked_add

[Manishearth]

Safety bug identified during agentic unsafe Rust audit.

This is kind of an obvious invariant but it's technically missing from the docs.

[rustbot]

r? @joboet

rustbot has assigned @joboet.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

• Owners of files modified in this PR: libs
• libs expanded to 12 candidates
• Random selection from 6 candidates

[rustbot]

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.

[jhpratt]

This actually seems correct? It starts with a nonzero value and you're adding an unsigned value, so zero inherently cannot occur without wrapping — which is already called out as UB.

[ds84182]

Since overflow cannot occur, unchecked_add is modeled as infinite precision integer addition with the caveat that "your house may explode" if the result exceeds a certain limit. Mathematically there are no non-negative integers that can be added to a positive integer that results in 0.

So I think this can be left to the developer's common sense.

Also the type is named NonZero.

[Manishearth]

Aha, I was looking through this macro to try and understand this code and didn't realize this macro was only applying to unsigned types. Thanks!

Also the type is named NonZero.

From a safety review perspective I always prefer explicitly documented invariants.

You'd be surprised how many people incorrectly call MaybeUninit::assume_init() despite it being in the name, it's by far the biggest safety goof I see.

[jhpratt]

I definitely see that a fair amount as well. I'm not opposed to explicitly documenting it, but I don't think it's particularly necessary given the current wording 👍