Documentation/rust/coding-guidelines.rst

1 .. SPDX-License-Identifier: GPL-2.0
10 ------------------
37 Like ``clang-format`` for the rest of the kernel, ``rustfmt`` works on
43 --------
51 .. code-block:: rust
60 .. code-block:: rust
73 .. code-block:: rust
84 	pub fn f(x: i32) -> Foo {
92 .. code-block:: rust
106 ------------------
108 Rust kernel code is not documented like C kernel code (i.e. via kernel-doc).
117 This is how a well-documented Rust function may look like:
119 .. code-block:: rust
121 	/// Returns the contained [`Some`] value, consuming the `self` value,
128 	/// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html
136 	pub unsafe fn unwrap_unchecked(self) -> T {
137 	    match self {
148   - The first paragraph must be a single sentence briefly describing what
151   - Unsafe functions must document their safety preconditions under
154   - While not shown here, if a function may panic, the conditions under which
161   - If providing examples of usage would help readers, they must be written in
164   - Rust items (functions, types, constants...) must be linked appropriately
167   - Any ``unsafe`` block must be preceded by a ``// SAFETY:`` comment
168     describing why the code inside is sound.
178 	https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html
183 .. code-block:: rust
189 .. code-block:: rust
195 ------
199 	https://rust-lang.github.io/api-guidelines/naming.html
211 .. code-block:: c
218 .. code-block:: rust