Commit 139d3965 authored by Miguel Ojeda's avatar Miguel Ojeda
Browse files

Documentation: rust: add coding guidelines on lints 



In the C side, disabling diagnostics locally, i.e. within the source code,
is rare (at least in the kernel). Sometimes warnings are manipulated
via the flags at the translation unit level, but that is about it.

In Rust, it is easier to change locally the "level" of lints
(e.g. allowing them locally). In turn, this means it is easier to
globally enable more lints that may trigger a few false positives here
and there that need to be allowed locally, but that generally can spot
issues or bugs.

Thus document this.

Reviewed-by: default avatarTrevor Gross <tmgross@umich.edu>
Reviewed-by: default avatarAlice Ryhl <aliceryhl@google.com>
Tested-by: default avatarGary Guo <gary@garyguo.net>
Reviewed-by: default avatarGary Guo <gary@garyguo.net>
Link: https://lore.kernel.org/r/20240904204347.168520-17-ojeda@kernel.org


Signed-off-by: default avatarMiguel Ojeda <ojeda@kernel.org>
parent 624063b9

Documentation/rust/coding-guidelines.rst

+38 −0
Original line number Diff line number Diff line
@@ -227,3 +227,41 @@ The equivalent in Rust may look like (ignoring documentation): 
That is, the equivalent of ``GPIO_LINE_DIRECTION_IN`` would be referred to as

``gpio::LineDirection::In``. In particular, it should not be named

``gpio::gpio_line_direction::GPIO_LINE_DIRECTION_IN``.





Lints

-----



In Rust, it is possible to ``allow`` particular warnings (diagnostics, lints)

locally, making the compiler ignore instances of a given warning within a given

function, module, block, etc.



It is similar to ``#pragma GCC diagnostic push`` + ``ignored`` + ``pop`` in C

[#]_:



.. code-block:: c



	#pragma GCC diagnostic push

	#pragma GCC diagnostic ignored "-Wunused-function"

	static void f(void) {}

	#pragma GCC diagnostic pop



.. [#] In this particular case, the kernel's ``__{always,maybe}_unused``

       attributes (C23's ``[[maybe_unused]]``) may be used; however, the example

       is meant to reflect the equivalent lint in Rust discussed afterwards.



But way less verbose:



.. code-block:: rust



	#[allow(dead_code)]

	fn f() {}



By that virtue, it makes it possible to comfortably enable more diagnostics by

default (i.e. outside ``W=`` levels). In particular, those that may have some

false positives but that are otherwise quite useful to keep enabled to catch

potential mistakes.



For more information about diagnostics in Rust, please see:



	https://doc.rust-lang.org/stable/reference/attributes/diagnostics.html