Skip to content

Commit afab3be

Browse files
ojedaojeda
committed
doc: rust: reorganize docs and coding
This separates the general information / concepts from the coding guidelines. Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
1 parent 888433d commit afab3be

5 files changed

Lines changed: 68 additions & 69 deletions

File tree

‎Documentation/process/changes.rst‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -368,8 +368,9 @@ for details about Sphinx requirements.
368368
rustdoc
369369
-------
370370

371-
``rustdoc`` is used to generate Rust documentation. Please see
372-
:ref:`Documentation/rust/docs.rst <rust_docs>` for more information.
371+
``rustdoc`` is used to generate the documentation for Rust code. Please see
372+
:ref:`Documentation/rust/general-information.rst <rust_general_information>`
373+
for more information.
373374

374375
Getting updated software
375376
========================

Documentation/rust/docs.rst renamed to Documentation/rust/coding-guidelines.rst

Lines changed: 37 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,55 @@
1-
.. _rust_docs:
1+
.. _rust_coding_guidelines:
22

3-
Docs
4-
====
3+
Coding Guidelines
4+
=================
55

6-
This document describes how to make the most out of the kernel documentation
7-
for Rust.
6+
This document describes how to write Rust code in the kernel.
87

9-
Rust kernel code is not documented like C kernel code (i.e. via kernel-doc).
10-
Instead, the usual system for documenting Rust code is used: the ``rustdoc``
11-
tool, which uses Markdown (a lightweight markup language).
128

13-
To learn Markdown, there are many guides available out there. For instance,
14-
the one at:
9+
Style & formatting
10+
------------------
1511

16-
https://commonmark.org/help/
12+
The code should be formatted using ``rustfmt``. In this way, a person
13+
contributing from time to time to the kernel does not need to learn and
14+
remember one more style guide. More importantly, reviewers and maintainers
15+
do not need to spend time pointing out style issues anymore, and thus
16+
less patch roundtrips may be needed to land a change.
17+
18+
.. note:: Conventions on comments and documentation are not checked by
19+
``rustfmt``. Thus those are still needed to be taken care of.
1720

21+
The default settings of ``rustfmt`` are used. This means the idiomatic Rust
22+
style is followed. For instance, 4 spaces are used for indentation rather
23+
than tabs.
1824

19-
Reading the docs
20-
----------------
25+
It is convenient to instruct editors/IDEs to format while typing,
26+
when saving or at commit time. However, if for some reason reformatting
27+
the entire kernel Rust sources is needed at some point, the following can be
28+
run::
2129

22-
The generated HTML docs produced by ``rustdoc`` include integrated search,
23-
linked items (e.g. types, functions, constants), source code, etc.
30+
make LLVM=1 rustfmt
2431

25-
The generated docs may be read at (TODO: link when in mainline and generated
26-
alongside the rest of the documentation):
32+
It is also possible to check if everything is formatted (printing a diff
33+
otherwise), for instance for a CI, with::
2734

28-
http://kernel.org/
35+
make LLVM=1 rustfmtcheck
2936

30-
The docs can also be easily generated and read locally. This is quite fast
31-
(same order as compiling the code itself) and no special tools or environment
32-
are needed. This has the added advantage that they will be tailored to
33-
the particular kernel configuration used. To generate them, use the ``rustdoc``
34-
target with the same invocation used for compilation, e.g.::
37+
Like ``clang-format`` for the rest of the kernel, ``rustfmt`` works on
38+
individual files, and does not require a kernel configuration. Sometimes it may
39+
even work with broken code.
3540

36-
make LLVM=1 rustdoc
3741

38-
To read the docs locally in your web browser, run e.g.::
42+
Code documentation
43+
------------------
3944

40-
xdg-open rust/doc/kernel/index.html
45+
Rust kernel code is not documented like C kernel code (i.e. via kernel-doc).
46+
Instead, the usual system for documenting Rust code is used: the ``rustdoc``
47+
tool, which uses Markdown (a lightweight markup language).
4148

42-
Writing the docs
43-
----------------
49+
To learn Markdown, there are many guides available out there. For instance,
50+
the one at:
51+
52+
https://commonmark.org/help/
4453

4554
This is how a well-documented Rust function may look like::
4655

Documentation/rust/coding.rst renamed to Documentation/rust/general-information.rst

Lines changed: 23 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,38 @@
1-
.. _rust_coding:
1+
.. _rust_general_information:
22

3-
Coding
4-
======
3+
General Information
4+
===================
55

6-
This document describes how to write Rust code in the kernel.
6+
This document contains useful information to know when working with
7+
the Rust support in the kernel.
78

89

9-
Coding style
10-
------------
10+
Code documentation
11+
------------------
1112

12-
The code should be formatted using ``rustfmt``. In this way, a person
13-
contributing from time to time to the kernel does not need to learn and
14-
remember one more style guide. More importantly, reviewers and maintainers
15-
do not need to spend time pointing out style issues anymore, and thus
16-
less patch roundtrips may be needed to land a change.
13+
Rust kernel code is documented using ``rustdoc``, its built-in documentation
14+
generator.
1715

18-
.. note:: Conventions on comments and documentation are not checked by
19-
``rustfmt``. Thus those are still needed to be taken care of: please see
20-
:ref:`Documentation/rust/docs.rst <rust_docs>`.
16+
The generated HTML docs include integrated search, linked items (e.g. types,
17+
functions, constants), source code, etc. They may be read at (TODO: link when
18+
in mainline and generated alongside the rest of the documentation):
2119

22-
The default settings of ``rustfmt`` are used. This means the idiomatic Rust
23-
style is followed. For instance, 4 spaces are used for indentation rather
24-
than tabs.
20+
http://kernel.org/
2521

26-
It is convenient to instruct editors/IDEs to format while typing,
27-
when saving or at commit time. However, if for some reason reformatting
28-
the entire kernel Rust sources is needed at some point, the following can be
29-
run::
22+
The docs can also be easily generated and read locally. This is quite fast
23+
(same order as compiling the code itself) and no special tools or environment
24+
are needed. This has the added advantage that they will be tailored to
25+
the particular kernel configuration used. To generate them, use the ``rustdoc``
26+
target with the same invocation used for compilation, e.g.::
3027

31-
make LLVM=1 rustfmt
28+
make LLVM=1 rustdoc
3229

33-
It is also possible to check if everything is formatted (printing a diff
34-
otherwise), for instance for a CI, with::
30+
To read the docs locally in your web browser, run e.g.::
3531

36-
make LLVM=1 rustfmtcheck
32+
xdg-open rust/doc/kernel/index.html
3733

38-
Like ``clang-format`` for the rest of the kernel, ``rustfmt`` works on
39-
individual files, and does not require a kernel configuration. Sometimes it may
40-
even work with broken code.
34+
To learn about how to write the documentation, please see the coding guidelines
35+
at :ref:`Documentation/rust/coding-guidelines.rst <rust_coding_guidelines>`.
4136

4237

4338
Extra lints
@@ -83,9 +78,3 @@ configuration:
8378
#[cfg(CONFIG_X="y")] // Enabled as a built-in (`y`)
8479
#[cfg(CONFIG_X="m")] // Enabled as a module (`m`)
8580
#[cfg(not(CONFIG_X))] // Disabled
86-
87-
88-
Documentation
89-
-------------
90-
91-
Please see :ref:`Documentation/rust/docs.rst <rust_docs>`.

‎Documentation/rust/index.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,8 @@ in the kernel, please read the
99
:maxdepth: 1
1010

1111
quick-start
12-
coding
13-
docs
12+
general-information
13+
coding-guidelines
1414
arch-support
1515

1616
.. only:: subproject and html

‎Documentation/rust/quick-start.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,7 @@ rustfmt
113113

114114
The ``rustfmt`` tool is used to automatically format all the Rust kernel code,
115115
including the generated C bindings (for details, please see
116-
:ref:`Documentation/rust/coding.rst <rust_coding>`).
116+
:ref:`Documentation/rust/coding-guidelines.rst <rust_coding_guidelines>`).
117117

118118
If ``rustup`` is being used, its ``default`` profile already installs the tool,
119119
thus nothing needs to be done. If another profile is being used, the component
@@ -129,7 +129,7 @@ clippy
129129

130130
``clippy`` is a Rust linter. Running it provides extra warnings for Rust code.
131131
It can be run by passing ``CLIPPY=1`` to ``make`` (for details, please see
132-
:ref:`Documentation/rust/coding.rst <rust_coding>`).
132+
:ref:`Documentation/rust/general-information.rst <rust_general_information>`).
133133

134134
If ``rustup`` is being used, its ``default`` profile already installs the tool,
135135
thus nothing needs to be done. If another profile is being used, the component
@@ -159,7 +159,7 @@ rustdoc
159159

160160
``rustdoc`` is the documentation tool for Rust. It generates pretty HTML
161161
documentation for Rust code (for details, please see
162-
:ref:`Documentation/rust/docs.rst <rust_docs>`).
162+
:ref:`Documentation/rust/general-information.rst <rust_general_information>`).
163163

164164
``rustdoc`` is also used to test the examples provided in documented Rust code
165165
(called doctests or documentation tests). The ``rusttest`` Make target uses

0 commit comments

Comments
 (0)