Re: [PATCH v2 3/4] rust: rework `build_assert!` documentation

[Yury Norov <ynorov@nvidia.com>]

On Mon, Mar 16, 2026 at 03:07:14PM +0000, Gary Guo wrote:
> From: Gary Guo <gary@garyguo.net>
> 
> Add a detailed comparison and recommendation of the three types of
> build-time assertion macro as module documentation (and un-hide the module
> to render them).
> 
> The documentation on the macro themselves are simplified to only cover the
> scenarios where they should be used; links to the module documentation is
> added instead.
> 
> Signed-off-by: Gary Guo <gary@garyguo.net>
> ---
>  rust/kernel/build_assert.rs | 113 +++++++++++++++++++++++++++---------
>  rust/kernel/lib.rs          |   1 -
>  2 files changed, 87 insertions(+), 27 deletions(-)
> 
> diff --git a/rust/kernel/build_assert.rs b/rust/kernel/build_assert.rs
> index 51c0f85a9014..acdfcbeb73f3 100644
> --- a/rust/kernel/build_assert.rs
> +++ b/rust/kernel/build_assert.rs
> @@ -1,6 +1,72 @@
>  // SPDX-License-Identifier: GPL-2.0
>  
>  //! Various assertions that happen during build-time.
> +//!
> +//! There are three types of build-time assertions that you can use:
> +//! - [`static_assert!`]
> +//! - [`const_assert!`]
> +//! - [`build_assert!`]
> +//!
> +//! The ones towards the bottom of the list are more expressive, while the ones towards the top of
> +//! the list are more robust and trigger earlier in the compilation pipeline. Therefore, you should
> +//! prefer the ones towards the top of the list wherever possible.
> +//!
> +//! # Choosing the correct assertion
> +//!
> +//! If you're asserting outside any bodies (e.g. initializers or function bodies), you should use
> +//! [`static_assert!`] as it is the only assertion that can be used in that context.
> +//!
> +//! Inside bodies, if your assertion condition does not depend on any variable or generics, you
> +//! should use [`static_assert!`]. If the condition depends on generics, but not variables (including
> +//! function arguments), you should use [`const_assert!`]. Otherwise, use [`build_assert!`].
> +//! The same is true regardless if the function is `const fn`.
> +//!
> +//! ```
> +//! // Outside any bodies
> +//! static_assert!(core::mem::size_of::<u8>() == 1);
> +//! // `const_assert!` and `build_assert!` cannot be used here, they will fail to compile.
> +//!
> +//! #[inline(always)]
> +//! fn foo<const N: usize>(v: usize) {
> +//!     static_assert!(core::mem::size_of::<u8>() == 1); // Preferred
> +//!     const_assert!(core::mem::size_of::<u8>() == 1); // Discouraged
> +//!     build_assert!(core::mem::size_of::<u8>() == 1); // Discouraged
> +//!
> +//!     // `static_assert!(N > 1);` is not allowed
> +//!     const_assert!(N > 1); // Preferred
> +//!     build_assert!(N > 1); // Discouraged
> +//!
> +//!     // `static_assert!(v > 1);` is not allowed
> +//!     // `const_assert!(v > 1);` is not allowed
> +//!     build_assert!(v > 1); // Works
> +//! }
> +//! ```
> +//!
> +//! # Detailed behavior
> +//!
> +//! `static_assert!()` is equivalent to `static_assert` in C. It requires `expr` to be a constant
> +//! expression. This expression cannot refer to any generics. A `static_assert!(expr)` in a program
> +//! is always evaluated, regardless if the function it appears in is used or not. This is also the
> +//! only usable assertion outside a body.
> +//!
> +//! `const_assert!()` has no direct C equivalence. It is a more powerful version of
> +//! `static_assert!()`, where it may refer to generics in a function. Note that due to the ability
> +//! to refer to generics, the assertion is tied to a specific instance of a function. So if it is
> +//! used in a generic function that is not instantiated, the assertion will not be checked. For this
> +//! reason, `static_assert!()` is preferred wherever possible.
> +//!
> +//! `build_assert!()` is equivalent to `BUILD_BUG_ON`. It is even more powerful than
> +//! `const_assert!()` because it can be used to check tautologies that depend on runtime value (this
> +//! is the same as `BUILD_BUG_ON`). However, the assertion failure mechanism can possibly be undefined
> +//! symbols and linker errors, it is not developer friendly to debug, so it is recommended to avoid it
> +//! and prefer other two assertions where possible.
> +
> +pub use crate::{
> +    build_assert,
> +    build_error,
> +    const_assert,
> +    static_assert, //
> +};

Solid wording, thank you!

For the series:
Reviewed-by: Yury Norov <ynorov@nvidia.com>
  
>  #[doc(hidden)]
>  pub use build_error::build_error;
> @@ -15,6 +81,10 @@
>  ///
>  /// The feature may be added to Rust in the future: see [RFC 2790].
>  ///
> +/// You cannot refer to generics or variables with [`static_assert!`]. If you need to refer to
> +/// generics, use [`const_assert!`]; if you need to refer to variables, use [`build_assert!`]. See
> +/// the [module documentation](self).
> +///
>  /// [`_Static_assert`]: https://en.cppreference.com/w/c/language/_Static_assert
>  /// [`static_assert`]: https://en.cppreference.com/w/cpp/language/static_assert
>  /// [RFC 2790]: https://github.com/rust-lang/rfcs/issues/2790
> @@ -47,6 +117,10 @@ macro_rules! static_assert {
>  /// or implementation blocks. However, it also has a limitation where it can only appear in places
>  /// where statements can appear; for example, you cannot use it as an item in the module.
>  ///
> +/// [`static_assert!`] should be preferred if no generics are referred to in the condition. You
> +/// cannot refer to variables with [`const_assert!`] (even inside `const fn`); if you need the
> +/// capability, use [`build_assert!`]. See the [module documentation](self).
> +///
>  /// # Examples
>  ///
>  /// ```
> @@ -98,41 +172,28 @@ macro_rules! build_error {
>  /// will panic. If the compiler or optimizer cannot guarantee the condition will
>  /// be evaluated to `true`, a build error will be triggered.
>  ///
> -/// [`static_assert!`] should be preferred to `build_assert!` whenever possible.
> +/// If the assertion condition does not depend on any variables or generics, you should use
> +/// [`static_assert!`]. If the assertion condition does not depend on variables, but does depend on
> +/// generics, you should use [`const_assert!`]. See the [module documentation](self).
>  ///
>  /// # Examples
>  ///
> -/// These examples show that different types of [`assert!`] will trigger errors
> -/// at different stage of compilation. It is preferred to err as early as
> -/// possible, so [`static_assert!`] should be used whenever possible.
> -/// ```ignore
> -/// fn foo() {
> -///     static_assert!(1 > 1); // Compile-time error
> -///     build_assert!(1 > 1); // Build-time error
> -///     assert!(1 > 1); // Run-time error
> -/// }
>  /// ```
> +/// #[inline(always)]
> +/// fn bar(n: usize) {
> +///     build_assert!(n > 1);
> +/// }
>  ///
> -/// When the condition refers to generic parameters or parameters of an inline function,
> -/// [`static_assert!`] cannot be used. Use `build_assert!` in this scenario.
> -/// ```
> -/// fn foo<const N: usize>() {
> -///     // `static_assert!(N > 1);` is not allowed
> -///     build_assert!(N > 1); // Build-time check
> -///     assert!(N > 1); // Run-time check
> +/// fn foo() {
> +///     bar(1);
>  /// }
> -/// ```
>  ///
> -/// When a condition depends on a function argument, the function must be annotated with
> -/// `#[inline(always)]`. Without this attribute, the compiler may choose to not inline the
> -/// function, preventing it from optimizing out the error path.
> -/// ```
>  /// #[inline(always)]
> -/// fn bar(n: usize) {
> -///     // `static_assert!(n > 1);` is not allowed
> -///     build_assert!(n > 1); // Build-time check
> -///     assert!(n > 1); // Run-time check
> +/// const fn const_bar(n: usize) {
> +///     build_assert!(n > 1);
>  /// }
> +///
> +/// const _: () = const_bar(2);
>  /// ```
>  #[macro_export]
>  macro_rules! build_assert {
> diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs
> index d590f7af54bf..1857e06e51f3 100644
> --- a/rust/kernel/lib.rs
> +++ b/rust/kernel/lib.rs
> @@ -77,7 +77,6 @@
>  #[cfg(CONFIG_BLOCK)]
>  pub mod block;
>  pub mod bug;
> -#[doc(hidden)]
>  pub mod build_assert;
>  pub mod clk;
>  #[cfg(CONFIG_CONFIGFS_FS)]
> -- 
> 2.51.2