rust: num: clean up Bounded::__new documentation and comments

[PATCH] rust: num: clean up Bounded::__new documentation and comments

Posted by Shivam Kalra 2 weeks ago

Remove the redundant paragraph in the documentation of __new now that
the Safety section explicitly covers the requirement. Additionally,
add an INVARIANT comment inside the function body where the Bounded
instance is actually constructed to document that the type invariant
is upheld.

Link: https://lore.kernel.org/rust-for-linux/CANiq72mUCUh72BWP4eD1PTDpwdb1ML+Xgfom-Ys6thJooqQPwQ@mail.gmail.com/.
Suggested-by: Miguel Ojeda <ojeda@kernel.org>
Signed-off-by: Shivam Kalra <shivamklr@cock.li>
---
 rust/kernel/num/bounded.rs | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/rust/kernel/num/bounded.rs b/rust/kernel/num/bounded.rs
index 5ef8361cf..fa81acbdc 100644
--- a/rust/kernel/num/bounded.rs
+++ b/rust/kernel/num/bounded.rs
@@ -282,9 +282,6 @@ impl<T, const N: u32> Bounded<T, N>
     /// All instances of [`Bounded`] must be created through this method as it enforces most of the
     /// type invariants.
     ///
-    /// The caller remains responsible for checking, either statically or dynamically, that `value`
-    /// can be represented as a `T` using at most `N` bits.
-    ///
     /// # Safety
     ///
     /// The caller must ensure that `value` can be represented within `N` bits.
@@ -297,6 +294,7 @@ impl<T, const N: u32> Bounded<T, N>
             assert!(N <= T::BITS);
         }
 
+        // INVARIANT: The caller ensures `value` fits within `N` bits.
         Self(value)
     }
 
-- 
2.43.0

Re: [PATCH] rust: num: clean up Bounded::__new documentation and comments

Posted by Miguel Ojeda 1 week, 5 days ago

On Fri, Jan 23, 2026 at 2:24 PM Shivam Kalra <shivamklr@cock.li> wrote:
>
> Remove the redundant paragraph in the documentation of __new now that
> the Safety section explicitly covers the requirement. Additionally,
> add an INVARIANT comment inside the function body where the Bounded
> instance is actually constructed to document that the type invariant
> is upheld.
>
> Link: https://lore.kernel.org/rust-for-linux/CANiq72mUCUh72BWP4eD1PTDpwdb1ML+Xgfom-Ys6thJooqQPwQ@mail.gmail.com/.
> Suggested-by: Miguel Ojeda <ojeda@kernel.org>
> Signed-off-by: Shivam Kalra <shivamklr@cock.li>

Applied to `rust-fixes` (because it cleans up the other one there) --
thanks everyone!

    [ Reworded slightly. - Miguel ]

Cheers,
Miguel

Re: [PATCH] rust: num: clean up Bounded::__new documentation and comments

Posted by Alexandre Courbot 1 week, 6 days ago

On Fri Jan 23, 2026 at 10:21 PM JST, Shivam Kalra wrote:
> Remove the redundant paragraph in the documentation of __new now that
> the Safety section explicitly covers the requirement. Additionally,
> add an INVARIANT comment inside the function body where the Bounded
> instance is actually constructed to document that the type invariant
> is upheld.
>
> Link: https://lore.kernel.org/rust-for-linux/CANiq72mUCUh72BWP4eD1PTDpwdb1ML+Xgfom-Ys6thJooqQPwQ@mail.gmail.com/.
> Suggested-by: Miguel Ojeda <ojeda@kernel.org>
> Signed-off-by: Shivam Kalra <shivamklr@cock.li>

Thanks for following up on this!

Acked-by: Alexandre Courbot <acourbot@nvidia.com>