[PATCH] rust: error: clarify that `from_err_ptr` can return `Ok(NULL)`

[Mirko Adzic <adzicmirko97@gmail.com>]

Improve the doc comment of `from_err_ptr` by explicitly stating that it
will return `Ok(NULL)` when passed a null pointer, as it isn't an error
value.

Add a doctest case that tests the behavior described above, as well as
other scenarios (non-null/non-error pointer, error value).

Suggested-by: Miguel Ojeda <ojeda@kernel.org>
Link: https://lore.kernel.org/rust-for-linux/20260322193830.89324-1-ojeda@kernel.org/
Link: https://github.com/Rust-for-Linux/linux/issues/1231
Signed-off-by: Mirko Adzic <adzicmirko97@gmail.com>
---
 rust/kernel/error.rs | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/rust/kernel/error.rs b/rust/kernel/error.rs
index 935787c2a91c..9a4388c74f43 100644
--- a/rust/kernel/error.rs
+++ b/rust/kernel/error.rs
@@ -452,6 +452,9 @@ pub fn to_result(err: crate::ffi::c_int) -> Result {
 /// for errors. This function performs the check and converts the "error pointer"
 /// to a normal pointer in an idiomatic fashion.
 ///
+/// Note that a `NULL` pointer is not considered an error pointer, and is returned
+/// as-is, wrapped in `Ok`.
+///
 /// # Examples
 ///
 /// ```ignore
@@ -466,6 +469,41 @@ pub fn to_result(err: crate::ffi::c_int) -> Result {
 ///     from_err_ptr(unsafe { bindings::devm_platform_ioremap_resource(pdev.to_ptr(), index) })
 /// }
 /// ```
+///
+/// ```
+/// # use kernel::error::from_err_ptr;
+/// # mod bindings {
+/// #     use kernel::prelude::*;
+/// #     pub(super) unsafe fn einval_err_ptr() -> *mut kernel::ffi::c_void {
+/// #         let einval = -(kernel::bindings::EINVAL as isize);
+/// #         // SAFETY: `einval` is a valid error.
+/// #         unsafe { kernel::bindings::ERR_PTR(einval) }
+/// #     }
+/// #     pub(super) unsafe fn null_ptr() -> *mut kernel::ffi::c_void {
+/// #         core::ptr::null_mut()
+/// #     }
+/// #     pub(super) unsafe fn non_null_ptr() -> *mut kernel::ffi::c_void {
+/// #         0x1234 as *mut kernel::ffi::c_void
+/// #     }
+/// # }
+/// fn einval_err_ptr() {
+///     // SAFETY: ...
+///     let result = from_err_ptr(unsafe { bindings::einval_err_ptr() });
+///     assert_eq!(result, Err(EINVAL));
+/// }
+///
+/// fn null_ptr() {
+///     // SAFETY: ...
+///     let result = from_err_ptr(unsafe { bindings::null_ptr() });
+///     assert_eq!(result, Ok(core::ptr::null_mut()));
+/// }
+///
+/// fn non_null_ptr() {
+///     // SAFETY: ...
+///     let result = from_err_ptr(unsafe { bindings::non_null_ptr() });
+///     assert_eq!(result, Ok(0x1234 as *mut kernel::ffi::c_void));
+/// }
+/// ```
 pub fn from_err_ptr<T>(ptr: *mut T) -> Result<*mut T> {
     // CAST: Casting a pointer to `*const crate::ffi::c_void` is always valid.
     let const_ptr: *const crate::ffi::c_void = ptr.cast();
-- 
2.53.0