Merge pull request torvalds#687 from ojeda/docs

Documentation cleanups

Author: ojeda

Documentation/process/changes.rst

@@ -92,10 +92,10 @@ Each Rust toolchain comes with several "components", some of which are required
 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
-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.
+Please see Documentation/rust/quick-start.rst for instructions on how to
+satisfy 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)
 ------------------
@@ -369,8 +369,7 @@ rustdoc
 -------
 
 ``rustdoc`` is used to generate the documentation for Rust code. Please see
-:ref:`Documentation/rust/general-information.rst <rust_general_information>`
-for more information.
+Documentation/rust/general-information.rst for more information.
 
 Getting updated software
 ========================
@@ -391,12 +390,12 @@ Clang/LLVM
 Rust
 ----
 
-- :ref:`Documentation/rust/quick-start.rst <rust_quick_start>`.
+- Documentation/rust/quick-start.rst.
 
 bindgen
 -------
 
-- :ref:`Documentation/rust/quick-start.rst <rust_quick_start>`.
+- Documentation/rust/quick-start.rst.
 
 Make
 ----

Documentation/rust/arch-support.rst

@@ -1,12 +1,11 @@
-.. _rust_arch_support:
-
 Arch Support
 ============
 
 Currently, the Rust compiler (``rustc``) uses LLVM for code generation,
 which limits the supported architectures that can be targeted. In addition,
-support for building the kernel with LLVM/Clang varies (see :ref:`kbuild_llvm`).
-This support is needed for ``bindgen`` which uses ``libclang``.
+support for building the kernel with LLVM/Clang varies (please see
+Documentation/kbuild/llvm.rst). This support is needed for ``bindgen``
+which uses ``libclang``.
 
 Below is a general summary of architectures that currently work. Level of
 support corresponds to ``S`` values in the ``MAINTAINERS`` file.

Documentation/rust/coding-guidelines.rst

@@ -1,5 +1,3 @@
-.. _rust_coding_guidelines:
-
 Coding Guidelines
 =================
 
@@ -46,7 +44,7 @@ Comments
 with ``///`` or ``//!``) are written in Markdown the same way as documentation
 comments are, even though they will not be rendered. This improves consistency,
 simplifies the rules and allows to move content between the two kinds of
-comments more easily. For instance::
+comments more easily. For instance:
 
 .. code-block:: rust
 
@@ -55,7 +53,7 @@ comments more easily. For instance::
 
 Furthermore, just like documentation, comments are capitalized at the beginning
 of a sentence and ended with a period (even if it is a single sentence). This
-includes `// SAFETY: `, `// TODO: ` and other "tagged" comments, e.g.::
+includes ``// SAFETY:``, ``// TODO:`` and other "tagged" comments, e.g.:
 
 .. code-block:: rust
 
@@ -65,10 +63,10 @@ Comments should not be used for documentation purposes: comments are intended
 for implementation details, not users. This distinction is useful even if the
 reader of the source file is both an implementor and a user of an API. In fact,
 sometimes it is useful to use both comments and documentation at the same time.
-For instance, for a `TODO` list or to comment on the documentation itself. For
-the latter case, comments can be inserted in the middle; that is, closer to
+For instance, for a ``TODO`` list or to comment on the documentation itself.
+For the latter case, comments can be inserted in the middle; that is, closer to
 the line of documentation to be commented. For any other case, comments are
-written after the documentation, e.g.::
+written after the documentation, e.g.:
 
 .. code-block:: rust
 
@@ -82,21 +80,21 @@ written after the documentation, e.g.::
 	/// ```
 	// FIXME: Use fallible approach.
 	pub fn f(x: i32) -> Foo {
-		// ...
+	    // ...
 	}
 
-One special kind of comments are the `// SAFETY: ` comments. These must appear
-before every `unsafe` block, and they explain why the code inside the block is
-correct/sound, i.e. why it cannot trigger undefined behavior in any case, e.g.::
+One special kind of comments are the ``// SAFETY:`` comments. These must appear
+before every ``unsafe`` block, and they explain why the code inside the block is
+correct/sound, i.e. why it cannot trigger undefined behavior in any case, e.g.:
 
 .. code-block:: rust
 
 	// SAFETY: `p` is valid by the safety requirements.
 	unsafe { *p = 0; }
 
-`// SAFETY: ` comments are not to be confused with the `# Safety` sections in
-code documentation. ``# Safety`` sections specify the contract that callers
-(for functions) or implementors (for traits) need to abide by. ``// SAFETY: ``
+``// SAFETY:`` comments are not to be confused with the ``# Safety`` sections
+in code documentation. ``# Safety`` sections specify the contract that callers
+(for functions) or implementors (for traits) need to abide by. ``// SAFETY:``
 comments show why a call (for functions) or implementation (for traits) actually
 respects the preconditions stated in a ``# Safety`` section or the language
 reference.
@@ -134,12 +132,12 @@ This is how a well-documented Rust function may look like:
 	/// assert_eq!(unsafe { x.unwrap_unchecked() }, "air");
 	/// ```
 	pub unsafe fn unwrap_unchecked(self) -> T {
-		match self {
-			Some(val) => val,
+	    match self {
+	        Some(val) => val,
 
-			// SAFETY: The safety contract must be upheld by the caller.
-			None => unsafe { hint::unreachable_unchecked() },
-		}
+	        // 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
@@ -167,15 +165,15 @@ in the kernel:
   - 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.
+    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`_.
+please take a look at the ``rustdoc`` book at:
 
-.. _book: https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html
+	https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html
 
 
 Naming

Documentation/rust/general-information.rst

@@ -1,5 +1,3 @@
-.. _rust_general_information:
-
 General Information
 ===================
 
@@ -31,8 +29,7 @@ To read the docs locally in your web browser, run e.g.::
 
 	xdg-open rust/doc/kernel/index.html
 
-To learn about how to write the documentation, please see the coding guidelines
-at :ref:`Documentation/rust/coding-guidelines.rst <rust_coding_guidelines>`.
+To learn about how to write the documentation, please see coding-guidelines.rst.
 
 
 Extra lints

Documentation/rust/index.rst

@@ -2,8 +2,7 @@ Rust
 ====
 
 Documentation related to Rust within the kernel. To start using Rust
-in the kernel, please read the
-:ref:`Documentation/rust/quick-start.rst <rust_quick_start>` guide.
+in the kernel, please read the quick-start.rst guide.
 
 .. toctree::
     :maxdepth: 1

Documentation/rust/quick-start.rst

@@ -1,5 +1,3 @@
-.. _rust_quick_start:
-
 Quick Start
 ===========
 
@@ -86,8 +84,8 @@ Otherwise, building LLVM takes quite a while, but it is not a complex process:
 
 	https://llvm.org/docs/GettingStarted.html#getting-the-source-code-and-building-llvm
 
-See :ref:`Documentation/kbuild/llvm.rst <kbuild_llvm>` for more information and
-further ways to fetch pre-built releases and distribution packages.
+Please see Documentation/kbuild/llvm.rst for more information and further ways
+to fetch pre-built releases and distribution packages.
 
 
 bindgen
@@ -113,7 +111,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-guidelines.rst <rust_coding_guidelines>`).
+coding-guidelines.rst).
 
 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 +127,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/general-information.rst <rust_general_information>`).
+general-information.rst).
 
 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 +157,7 @@ rustdoc
 
 ``rustdoc`` is the documentation tool for Rust. It generates pretty HTML
 documentation for Rust code (for details, please see
-:ref:`Documentation/rust/general-information.rst <rust_general_information>`).
+general-information.rst).
 
 ``rustdoc`` is also used to test the examples provided in documented Rust code
 (called doctests or documentation tests). The ``rusttest`` Make target uses