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
67 sometimes it is useful to use both comments and documentation at the same time.
73 .. code-block:: rust
83 	// FIXME: Use fallible approach.
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
128 	/// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html
136 	pub unsafe fn unwrap_unchecked(self) -> T {
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
158   reason. In almost all cases, a fallible approach should be used, typically
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
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
233 -----
242 .. code-block:: c
245 	#pragma GCC diagnostic ignored "-Wunused-function"
255 .. code-block:: rust
270 .. code-block:: rust
278 	 --> x.rs:3:10
288 - Temporary attributes added while developing.
290 - Improvements in lints in the compiler, Clippy or custom tools which may
293 - When the lint is not needed anymore because it was expected that it would be
301 - Conditional compilation triggers the warning in some cases but not others.
303   If there are only a few cases where the warning triggers (or does not
304   trigger) compared to the total number of cases, then one may consider using
306   it is likely simpler to just use ``allow``.
308 - Inside macros, when the different invocations may create expanded code that
309   triggers the warning in some cases but not in others.
311 - When code may trigger a warning for some architectures but not others, such
316 .. code-block:: rust
325 Here, function ``g()`` is dead code if ``CONFIG_X`` is not set. Can we use
328 .. code-block:: rust
339 configuration. Therefore, in cases like this, we cannot use ``expect`` as-is.
343 .. code-block:: rust
355 .. code-block:: rust
371 triggered due to non-local changes (such as ``dead_code``).
375 	https://doc.rust-lang.org/stable/reference/attributes/diagnostics.html
378 --------------
383 	https://rust.docs.kernel.org/kernel/error/type.Result.html#error-codes-in-c-and-rust