linux-kernel.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Willy Tarreau <w@1wt.eu>
To: ojeda@kernel.org
Cc: Linus Torvalds <torvalds@linux-foundation.org>,
	Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
	rust-for-linux@vger.kernel.org, linux-kbuild@vger.kernel.org,
	linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
	Alex Gaynor <alex.gaynor@gmail.com>,
	Geoffrey Thomas <geofft@ldpreload.com>,
	Finn Behrens <me@kloenk.de>,
	Adam Bratschi-Kaye <ark.email@gmail.com>,
	Wedson Almeida Filho <wedsonaf@google.com>,
	Boqun Feng <boqun.feng@gmail.com>,
	Sumera Priyadarsini <sylphrenadin@gmail.com>,
	Michael Ellerman <mpe@ellerman.id.au>,
	Sven Van Asbroeck <thesven73@gmail.com>,
	Gary Guo <gary@garyguo.net>,
	Boris-Chengbiao Zhou <bobo1239@web.de>,
	Fox Chen <foxhlchen@gmail.com>,
	Ayaan Zaidi <zaidi.ayaan@gmail.com>,
	Douglas Su <d0u9.su@outlook.com>, Yuki Okushi <jtitor@2k36.org>
Subject: Re: [PATCH 13/17] docs: add Rust documentation
Date: Mon, 5 Jul 2021 07:02:34 +0200	[thread overview]
Message-ID: <20210705050234.GB30964@1wt.eu> (raw)
In-Reply-To: <20210704202756.29107-14-ojeda@kernel.org>

On Sun, Jul 04, 2021 at 10:27:52PM +0200, ojeda@kernel.org wrote:
> From: Miguel Ojeda <ojeda@kernel.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

  reply	other threads:[~2021-07-05  5:03 UTC|newest]

Thread overview: 73+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-07-04 20:27 [PATCH 00/17] Rust support ojeda
2021-07-04 20:27 ` [PATCH 01/17] kallsyms: support big kernel symbols (2-byte lengths) ojeda
2021-07-04 20:52   ` Linus Torvalds
2021-07-04 21:15     ` Miguel Ojeda
2021-07-04 21:28       ` Linus Torvalds
2021-07-04 21:04   ` Matthew Wilcox
2021-07-04 21:17     ` Miguel Ojeda
2021-07-04 21:33       ` Matthew Wilcox
2021-07-04 21:49         ` Matthew Wilcox
2021-07-04 22:07           ` Miguel Ojeda
2021-07-04 22:20         ` Gary Guo
2021-07-04 22:42           ` Matthew Wilcox
2021-07-04 23:14             ` Gary Guo
2021-07-13 18:02             ` Kent Overstreet
2021-07-04 21:20     ` Gary Guo
2021-07-05  4:35       ` Willy Tarreau
2021-07-04 20:27 ` [PATCH 02/17] kallsyms: increase maximum kernel symbol length to 512 ojeda
2021-07-14 18:20   ` Nick Desaulniers
2021-07-14 19:04     ` Linus Torvalds
2021-07-14 20:09       ` Eric W. Biederman
2021-07-14 20:21         ` Linus Torvalds
2021-07-14 20:48           ` Eric W. Biederman
2021-07-14 22:40             ` Linus Torvalds
2021-07-14 20:19     ` Miguel Ojeda
2021-07-04 20:27 ` [PATCH 03/17] Makefile: generate `CLANG_FLAGS` even in GCC builds ojeda
2021-07-14 18:13   ` Nick Desaulniers
2021-07-14 18:16     ` Nick Desaulniers
2021-07-14 20:31     ` Miguel Ojeda
2021-07-04 20:27 ` [PATCH 04/17] vsprintf: add new `%pA` format specifier ojeda
2021-07-07 20:31   ` Nick Desaulniers
2021-07-07 22:33     ` Miguel Ojeda
2021-07-04 20:27 ` [PATCH 05/17] rust: add C helpers ojeda
2021-07-07 10:19   ` Marco Elver
2021-07-09 10:31     ` Marco Elver
2021-07-09 14:32     ` Miguel Ojeda
2021-07-04 20:27 ` [PATCH 06/17] rust: add `compiler_builtins` crate ojeda
2021-07-04 20:27 ` [PATCH 07/17] rust: add `alloc` crate ojeda
2021-07-04 20:27 ` [PATCH 08/17] rust: add `build_error` crate ojeda
2021-07-04 20:27 ` [PATCH 09/17] rust: add `macros` crate ojeda
2021-07-04 20:27 ` [PATCH 10/17] rust: add `kernel` crate ojeda
2021-07-04 20:27 ` [PATCH 11/17] rust: export generated symbols ojeda
2021-07-04 20:27 ` [PATCH 12/17] Kbuild: add Rust support ojeda
2021-07-04 20:27 ` [PATCH 13/17] docs: add Rust documentation ojeda
2021-07-05  5:02   ` Willy Tarreau [this message]
2021-07-06  0:06     ` Miguel Ojeda
2021-07-06  2:09       ` Willy Tarreau
2021-07-14 18:37   ` Nick Desaulniers
2021-07-14 19:55     ` Miguel Ojeda
2021-07-04 20:27 ` [PATCH 14/17] samples: add Rust examples ojeda
2021-07-04 20:27 ` [PATCH 15/17] scripts: add `generate_rust_analyzer.py` ojeda
2021-07-05  5:05   ` Willy Tarreau
2021-07-05 23:41     ` Miguel Ojeda
2021-07-04 20:27 ` [PATCH 16/17] MAINTAINERS: Rust ojeda
2021-07-06  0:26   ` Pedro Tammela
2021-07-06 22:14     ` Miguel Ojeda
2021-07-04 20:27 ` [RFC PATCH 17/17] Android: Binder IPC in Rust (WIP) ojeda
2021-07-04 23:11 ` [PATCH 00/17] Rust support Miguel Ojeda
2021-07-07  6:43 ` Christoph Hellwig
2021-07-07 12:33   ` Miguel Ojeda
2021-07-07 12:50     ` Greg Kroah-Hartman
2021-07-07 14:07       ` Wedson Almeida Filho
2021-07-07 14:12         ` Christoph Hellwig
2021-07-07 15:02         ` Greg Kroah-Hartman
2021-07-07 20:56           ` Finn Behrens
2021-07-08  0:58             ` Matthew Wilcox
2021-07-08  6:39               ` [PATCH 00/17] Rust support, NVMe Geert Stappers
2021-07-08  8:29                 ` Finn Behrens
2021-07-22 22:55               ` [PATCH 00/17] Rust support Wedson Almeida Filho
2021-07-23  1:17                 ` Matthew Wilcox
2021-07-23 11:33                   ` [PATCH 00/17] Rust support, GPIO driver Geert Stappers
2021-07-23 15:08                 ` [PATCH 00/17] Rust support Keith Busch
2021-07-07 10:51 ` Marco Elver
2021-07-07 11:28   ` Miguel Ojeda

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20210705050234.GB30964@1wt.eu \
    --to=w@1wt.eu \
    --cc=alex.gaynor@gmail.com \
    --cc=ark.email@gmail.com \
    --cc=bobo1239@web.de \
    --cc=boqun.feng@gmail.com \
    --cc=d0u9.su@outlook.com \
    --cc=foxhlchen@gmail.com \
    --cc=gary@garyguo.net \
    --cc=geofft@ldpreload.com \
    --cc=gregkh@linuxfoundation.org \
    --cc=jtitor@2k36.org \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kbuild@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=me@kloenk.de \
    --cc=mpe@ellerman.id.au \
    --cc=ojeda@kernel.org \
    --cc=rust-for-linux@vger.kernel.org \
    --cc=sylphrenadin@gmail.com \
    --cc=thesven73@gmail.com \
    --cc=torvalds@linux-foundation.org \
    --cc=wedsonaf@google.com \
    --cc=zaidi.ayaan@gmail.com \
    --subject='Re: [PATCH 13/17] docs: add Rust documentation' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
on how to clone and mirror all data and code used for this inbox