Merge pull request #626 from ojeda/doc

ojeda · web-flow · commit 1648677fc363 · 2022-01-15T23:23:24.000+01:00
Documentation improvements
diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst
@@ -93,7 +93,9 @@ is optional) needs to be installed to build the kernel. Other components are
 useful for developing.
 
 Please see :ref:`Documentation/rust/quick-start.rst <rust_quick_start>` for
-more information.
+instructions on how to satify the build requirements of Rust support. In
+particular, the Makefile target 'rustavailable' is useful to check why the Rust
+toolchain may not be detected.
 
 bindgen (optional)
 ------------------
@@ -366,8 +368,9 @@ for details about Sphinx requirements.
 rustdoc
 -------
 
-``rustdoc`` is used to generate Rust documentation. Please see
-:ref:`Documentation/rust/docs.rst <rust_docs>` for more information.
+``rustdoc`` is used to generate the documentation for Rust code. Please see
+:ref:`Documentation/rust/general-information.rst <rust_general_information>`
+for more information.
 
 Getting updated software
 ========================
diff --git a/Documentation/rust/coding-guidelines.rst b/Documentation/rust/coding-guidelines.rst
@@ -0,0 +1,151 @@
+.. _rust_coding_guidelines:
+
+Coding Guidelines
+=================
+
+This document describes how to write Rust code in the kernel.
+
+
+Style & formatting
+------------------
+
+The code should be formatted using ``rustfmt``. In this way, a person
+contributing from time to time to the kernel does not need to learn and
+remember one more style guide. More importantly, reviewers and maintainers
+do not need to spend time pointing out style issues anymore, and thus
+less patch roundtrips may be needed to land a change.
+
+.. note:: Conventions on comments and documentation are not checked by
+  ``rustfmt``. Thus those are still needed to be taken care of.
+
+The default settings of ``rustfmt`` are used. This means the idiomatic Rust
+style is followed. For instance, 4 spaces are used for indentation rather
+than tabs.
+
+It is convenient to instruct editors/IDEs to format while typing,
+when saving or at commit time. However, if for some reason reformatting
+the entire kernel Rust sources is needed at some point, the following can be
+run::
+
+	make LLVM=1 rustfmt
+
+It is also possible to check if everything is formatted (printing a diff
+otherwise), for instance for a CI, with::
+
+	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.
+
+
+Code documentation
+------------------
+
+Rust kernel code is not documented like C kernel code (i.e. via kernel-doc).
+Instead, the usual system for documenting Rust code is used: the ``rustdoc``
+tool, which uses Markdown (a lightweight markup language).
+
+To learn Markdown, there are many guides available out there. For instance,
+the one at:
+
+	https://commonmark.org/help/
+
+This is how a well-documented Rust function may look like::
+
+	/// Returns the contained [`Some`] value, consuming the `self` value,
+	/// without checking that the value is not [`None`].
+	///
+	/// # Safety
+	///
+	/// Calling this method on [`None`] is *[undefined behavior]*.
+	///
+	/// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html
+	///
+	/// # Examples
+	///
+	/// ```
+	/// let x = Some("air");
+	/// assert_eq!(unsafe { x.unwrap_unchecked() }, "air");
+	/// ```
+	pub unsafe fn unwrap_unchecked(self) -> T {
+		match self {
+			Some(val) => val,
+
+			// SAFETY: the safety contract must be upheld by the caller.
+			None => unsafe { hint::unreachable_unchecked() },
+		}
+	}
+
+This example showcases a few ``rustdoc`` features and some conventions followed
+in the kernel:
+
+  - The first paragraph must be a single sentence briefly describing what
+    the documented item does. Further explanations must go in extra paragraphs.
+
+  - Unsafe functions must document their safety preconditions under
+    a ``# Safety`` section.
+
+  - While not shown here, if a function may panic, the conditions under which
+    that happens must be described under a ``# Panics`` section.
+
+    Please note that panicking should be very rare and used only with a good
+    reason. In almost all cases, a fallible approach should be used, typically
+    returning a ``Result``.
+
+  - If providing examples of usage would help readers, they must be written in
+    a section called ``# Examples``.
+
+  - Rust items (functions, types, constants...) must be linked appropriately
+    (``rustdoc`` will create a link automatically).
+
+  - Any ``unsafe`` block must be preceded by a ``// SAFETY:`` comment
+    describing why the code inside is sound.
+
+    While sometimes the reason might look trivial and therefore unneeded, writing
+    these comments is not just a good way of documenting what has been taken into
+    account, but most importantly, it provides a way to know that there are
+    no *extra* implicit constraints.
+
+To learn more about how to write documentation for Rust and extra features,
+please take a look at the ``rustdoc`` `book`_.
+
+.. _book: https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html
+
+
+Naming
+------
+
+Rust kernel code follows the usual Rust naming conventions:
+
+	https://rust-lang.github.io/api-guidelines/naming.html
+
+When existing C concepts (e.g. macros, functions, objects...) are wrapped into
+a Rust abstraction, a name as close as reasonably possible to the C side should
+be used in order to avoid confusion and to improve readability when switching
+back and forth between the C and Rust sides. For instance, macros such as
+``pr_info`` from C are named the same in the Rust side.
+
+Having said that, casing should be adjusted to follow the Rust naming
+conventions, and namespacing introduced by modules and types should not be
+repeated in the item names. For instance, when wrapping constants like:
+
+.. code-block:: c
+
+	#define GPIO_LINE_DIRECTION_IN	0
+	#define GPIO_LINE_DIRECTION_OUT	1
+
+The equivalent in Rust may look like (ignoring documentation):
+
+.. code-block:: rust
+
+	pub mod gpio {
+	    pub enum LineDirection {
+	        In = bindings::GPIO_LINE_DIRECTION_IN as _,
+	        Out = bindings::GPIO_LINE_DIRECTION_OUT as _,
+	    }
+	}
+
+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``.
diff --git a/Documentation/rust/docs.rst b/Documentation/rust/docs.rst
diff --git a/Documentation/rust/general-information.rst b/Documentation/rust/general-information.rst
@@ -1,43 +1,38 @@
-.. _rust_coding:
+.. _rust_general_information:
 
-Coding
-======
+General Information
+===================
 
-This document describes how to write Rust code in the kernel.
+This document contains useful information to know when working with
+the Rust support in the kernel.
 
 
-Coding style
-------------
+Code documentation
+------------------
 
-The code should be formatted using ``rustfmt``. In this way, a person
-contributing from time to time to the kernel does not need to learn and
-remember one more style guide. More importantly, reviewers and maintainers
-do not need to spend time pointing out style issues anymore, and thus
-less patch roundtrips may be needed to land a change.
+Rust kernel code is documented using ``rustdoc``, its built-in documentation
+generator.
 
-.. note:: Conventions on comments and documentation are not checked by
-  ``rustfmt``. Thus those are still needed to be taken care of: please see
-  :ref:`Documentation/rust/docs.rst <rust_docs>`.
+The generated HTML docs include integrated search, linked items (e.g. types,
+functions, constants), source code, etc. They may be read at (TODO: link when
+in mainline and generated alongside the rest of the documentation):
 
-The default settings of ``rustfmt`` are used. This means the idiomatic Rust
-style is followed. For instance, 4 spaces are used for indentation rather
-than tabs.
+	http://kernel.org/
 
-It is convenient to instruct editors/IDEs to format while typing,
-when saving or at commit time. However, if for some reason reformatting
-the entire kernel Rust sources is needed at some point, the following can be
-run::
+The docs can also be easily generated and read locally. This is quite fast
+(same order as compiling the code itself) and no special tools or environment
+are needed. This has the added advantage that they will be tailored to
+the particular kernel configuration used. To generate them, use the ``rustdoc``
+target with the same invocation used for compilation, e.g.::
 
-	make LLVM=1 rustfmt
+	make LLVM=1 rustdoc
 
-It is also possible to check if everything is formatted (printing a diff
-otherwise), for instance for a CI, with::
+To read the docs locally in your web browser, run e.g.::
 
-	make LLVM=1 rustfmtcheck
+	xdg-open rust/doc/kernel/index.html
 
-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.
+To learn about how to write the documentation, please see the coding guidelines
+at :ref:`Documentation/rust/coding-guidelines.rst <rust_coding_guidelines>`.
 
 
 Extra lints
@@ -83,9 +78,3 @@ configuration:
 	#[cfg(CONFIG_X="y")]   // Enabled as a built-in (`y`)
 	#[cfg(CONFIG_X="m")]   // Enabled as a module   (`m`)
 	#[cfg(not(CONFIG_X))]  // Disabled
-
-
-Documentation
--------------
-
-Please see :ref:`Documentation/rust/docs.rst <rust_docs>`.
diff --git a/Documentation/rust/index.rst b/Documentation/rust/index.rst
@@ -9,8 +9,8 @@ in the kernel, please read the
     :maxdepth: 1
 
     quick-start
-    coding
-    docs
+    general-information
+    coding-guidelines
     arch-support
 
 .. only::  subproject and html
diff --git a/Documentation/rust/quick-start.rst b/Documentation/rust/quick-start.rst
@@ -113,7 +113,7 @@ rustfmt
 
 The ``rustfmt`` tool is used to automatically format all the Rust kernel code,
 including the generated C bindings (for details, please see
-:ref:`Documentation/rust/coding.rst <rust_coding>`).
+:ref:`Documentation/rust/coding-guidelines.rst <rust_coding_guidelines>`).
 
 If ``rustup`` is being used, its ``default`` profile already installs the tool,
 thus nothing needs to be done. If another profile is being used, the component
@@ -129,7 +129,7 @@ clippy
 
 ``clippy`` is a Rust linter. Running it provides extra warnings for Rust code.
 It can be run by passing ``CLIPPY=1`` to ``make`` (for details, please see
-:ref:`Documentation/rust/coding.rst <rust_coding>`).
+:ref:`Documentation/rust/general-information.rst <rust_general_information>`).
 
 If ``rustup`` is being used, its ``default`` profile already installs the tool,
 thus nothing needs to be done. If another profile is being used, the component
@@ -159,7 +159,7 @@ rustdoc
 
 ``rustdoc`` is the documentation tool for Rust. It generates pretty HTML
 documentation for Rust code (for details, please see
-:ref:`Documentation/rust/docs.rst <rust_docs>`).
+:ref:`Documentation/rust/general-information.rst <rust_general_information>`).
 
 ``rustdoc`` is also used to test the examples provided in documented Rust code
 (called doctests or documentation tests). The ``rusttest`` Make target uses
