linux-kernel - Re: [PATCH 13/17] docs: add Rust documentation

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20210705050234.GB30964@1wt.eu>
Date:   Mon, 5 Jul 2021 07:02:34 +0200
From:   Willy Tarreau <w@....eu>
To:     ojeda@...nel.org
Cc:     Linus Torvalds <torvalds@...ux-foundation.org>,
        Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
        rust-for-linux@...r.kernel.org, linux-kbuild@...r.kernel.org,
        linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
        Alex Gaynor <alex.gaynor@...il.com>,
        Geoffrey Thomas <geofft@...reload.com>,
        Finn Behrens <me@...enk.de>,
        Adam Bratschi-Kaye <ark.email@...il.com>,
        Wedson Almeida Filho <wedsonaf@...gle.com>,
        Boqun Feng <boqun.feng@...il.com>,
        Sumera Priyadarsini <sylphrenadin@...il.com>,
        Michael Ellerman <mpe@...erman.id.au>,
        Sven Van Asbroeck <thesven73@...il.com>,
        Gary Guo <gary@...yguo.net>,
        Boris-Chengbiao Zhou <bobo1239@....de>,
        Fox Chen <foxhlchen@...il.com>,
        Ayaan Zaidi <zaidi.ayaan@...il.com>,
        Douglas Su <d0u9.su@...look.com>, Yuki Okushi <jtitor@...6.org>
Subject: Re: [PATCH 13/17] docs: add Rust documentation

On Sun, Jul 04, 2021 at 10:27:52PM +0200, ojeda@...nel.org wrote:
> From: Miguel Ojeda <ojeda@...nel.org>
> 
> Most of the documentation for Rust is written within the source code
> itself, as it is idiomatic for Rust projects. This applies to both
> the shared infrastructure at `rust/` as well as any other Rust module
> (e.g. drivers) written across the kernel.
(...)
> diff --git a/Documentation/rust/coding.rst b/Documentation/rust/coding.rst
> new file mode 100644
> index 00000000000..5cbe132f461
> --- /dev/null
> +++ b/Documentation/rust/coding.rst
> @@ -0,0 +1,92 @@
> +.. _rust_coding:
> +
> +Coding
> +======
> +
> +This document describes how to write Rust code in the kernel.
> +
> +
> +Coding style
> +------------
> +
> +The code is automatically formatted using the ``rustfmt`` tool. This is very
> +good news!

Miguel, the wording and style in this file is not much welcome, it looks
like a copy-paste of an e-mail in the doc. The exclamation above "this is
a very good news" doesn't really belong to a doc, and for readers who don't
understand why it appears as a good news to the writer, it probably is an
even less good news.

> +- If you contribute from time to time to the kernel, you do not need to learn
> +  and remember one more style guide. You will also need less patch roundtrips
> +  to land a change.
> +
> +- If you are a reviewer or a maintainer, you will not need to spend time on
> +  pointing out style issues anymore.
> +
> +.. note:: Conventions on comments and documentation are not checked by
> +  ``rustfmt``. Thus we still need to take care of those: please see
> +  :ref:`Documentation/rust/docs.rst <rust_docs>`.
> +
> +We use the tool's default settings. This means we are following the idiomatic
> +Rust style. For instance, we use 4 spaces for indentation rather than tabs.
> +
> +Typically, you will want to instruct your editor/IDE to format while you type,

In general you should avoid "we" and "you" when writing documentation.
Prefer passive forms instead, which do not place a barrier between those
who teach and those who learn. It's generally considered more inclusive
in that it makes the reader not feel outside of the team who wrote it.

For example the last sentences above could be reworded like this:

  The tool's default settings are used, which means the idiomatic Rust
  style is followed. For instance, 4 spaces are used for indentation
  rather than tabs.

  Typically editors/IDE will have to be instructed to format while typing.
  (...)

An additional note is that if the language imposes such unusual constraints
on the editor, you should probably point to various known settins for most
well-known editors.

> +when you save or at commit time. However, if for some reason you want
> +to reformat the entire kernel Rust sources at some point, you may run::
> +
> +	make LLVM=1 rustfmt
> +
> +To check if everything is formatted (printing a diff otherwise), e.g. if you
> +have configured a CI for a tree as a maintainer, you may run::
> +
> +	make LLVM=1 rustfmtcheck
> +
> +Like ``clang-format`` for the rest of the kernel, ``rustfmt`` works on
> +individual files, and does not require a kernel configuration. Sometimes it may
> +even work with broken code.

You should also clearly indicate how to recheck (or adjust) individual
files, not just say that the command supports it.

Regards,
Willy