Re: [PATCH 16/19] Documentation: rust: add coding guidelines on lints

From: Trevor Gross
Date: Sun Sep 29 2024 - 01:03:23 EST


On Wed, Sep 4, 2024 at 4:45 PM Miguel Ojeda <ojeda@xxxxxxxxxx> wrote:
>
> 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 ocally, but that generally can spot
> issues or bugs.

s/ocally/locally

> Thus document this.
>
> Signed-off-by: Miguel Ojeda <ojeda@xxxxxxxxxx>
> ---
> Documentation/rust/coding-guidelines.rst | 29 ++++++++++++++++++++++++
> 1 file changed, 29 insertions(+)
>
> diff --git a/Documentation/rust/coding-guidelines.rst b/Documentation/rust/coding-guidelines.rst
> index 05542840b16c..185d3b51117d 100644
> --- a/Documentation/rust/coding-guidelines.rst
> +++ b/Documentation/rust/coding-guidelines.rst
> @@ -227,3 +227,32 @@ 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
> +
> +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.

It may be good to link to the docs on this,
https://doc.rust-lang.org/stable/reference/attributes/diagnostics.html.
Either way:

Reviewed-by: Trevor Gross <tmgross@xxxxxxxxx>