[PATCH v2] docs: rust: Add error handling sections

[PATCH v2] docs: rust: Add error handling sections

[Dirk Behme]

Add error handling sections to the documentation and use it
to link to the existing code documentation. This will allow
to extend that documentation, use intra-doc links and test
the examples.

Suggested-by: Miguel Ojeda <ojeda@kernel.org>
Link: https://lore.kernel.org/rust-for-linux/CANiq72keOdXy0LFKk9SzYWwSjiD710v=hQO4xi+5E4xNALa6cA@mail.gmail.com/
Signed-off-by: Dirk Behme <dirk.behme@de.bosch.com>
---

Changes in v2: Rephrase the sentence about "real code" (Miguel)

 Documentation/rust/coding-guidelines.rst | 8 ++++++++
 Documentation/rust/testing.rst           | 8 ++++++++
 2 files changed, 16 insertions(+)

diff --git a/Documentation/rust/coding-guidelines.rst b/Documentation/rust/coding-guidelines.rst
index a2e326b42410f..27f2a7bb5a4a2 100644
--- a/Documentation/rust/coding-guidelines.rst
+++ b/Documentation/rust/coding-guidelines.rst
@@ -373,3 +373,11 @@ triggered due to non-local changes (such as ``dead_code``).
 For more information about diagnostics in Rust, please see:
 
 	https://doc.rust-lang.org/stable/reference/attributes/diagnostics.html
+
+Error handling
+--------------
+
+For some background and guidelines about Rust for Linux specific error handling,
+please see:
+
+	https://rust.docs.kernel.org/kernel/error/type.Result.html#error-codes-in-c-and-rust
diff --git a/Documentation/rust/testing.rst b/Documentation/rust/testing.rst
index 568b71b415a45..78b66b67b03fe 100644
--- a/Documentation/rust/testing.rst
+++ b/Documentation/rust/testing.rst
@@ -123,6 +123,14 @@ A current limitation is that KUnit does not support assertions in other tasks.
 Thus, we presently simply print an error to the kernel log if an assertion
 actually failed. Additionally, doctests are not run for nonpublic functions.
 
+Since these tests are examples, i.e. they are part of the documentation, they
+should generally be written like "real code". Thus, for example, instead of
+using ``unwrap()``/``expect()`` use the ``?``-operator. See:
+
+	https://rust.docs.kernel.org/kernel/error/type.Result.html#error-codes-in-c-and-rust
+
+for some background.
+
 The ``#[test]`` tests
 ---------------------
 
-- 
2.48.0

Re: [PATCH v2] docs: rust: Add error handling sections

[Miguel Ojeda]

On Wed, Jan 15, 2025 at 7:26 AM Dirk Behme <dirk.behme@de.bosch.com> wrote:
>
> Add error handling sections to the documentation and use it
> to link to the existing code documentation. This will allow
> to extend that documentation, use intra-doc links and test
> the examples.
>
> Suggested-by: Miguel Ojeda <ojeda@kernel.org>
> Link: https://lore.kernel.org/rust-for-linux/CANiq72keOdXy0LFKk9SzYWwSjiD710v=hQO4xi+5E4xNALa6cA@mail.gmail.com/
> Signed-off-by: Dirk Behme <dirk.behme@de.bosch.com>

Applied to `rust-next` -- thanks!

    [ Slightly tweaked wording. - Miguel ]

Cheers,
Miguel