Skip to content

Commit 2040dd3

Browse files
committed
doc: coding-guidelines: add Naming subsection
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
1 parent afab3be commit 2040dd3

File tree

1 file changed

+38
-0
lines changed

1 file changed

+38
-0
lines changed

Documentation/rust/coding-guidelines.rst

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -111,3 +111,41 @@ To learn more about how to write documentation for Rust and extra features,
111111
please take a look at the ``rustdoc`` `book`_.
112112

113113
.. _book: https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html
114+
115+
116+
Naming
117+
------
118+
119+
Rust kernel code follows the usual Rust naming conventions:
120+
121+
https://rust-lang.github.io/api-guidelines/naming.html
122+
123+
When existing C concepts (e.g. macros, functions, objects...) are wrapped into
124+
a Rust abstraction, a name as close as reasonably possible to the C side should
125+
be used in order to avoid confusion and to improve readability when switching
126+
back and forth between the C and Rust sides. For instance, macros such as
127+
``pr_info`` from C are named the same in the Rust side.
128+
129+
Having said that, casing should be adjusted to follow the Rust naming
130+
conventions, and namespacing introduced by modules and types should not be
131+
repeated in the item names. For instance, when wrapping constants like:
132+
133+
.. code-block:: c
134+
135+
#define GPIO_LINE_DIRECTION_IN 0
136+
#define GPIO_LINE_DIRECTION_OUT 1
137+
138+
The equivalent in Rust may look like (ignoring documentation):
139+
140+
.. code-block:: rust
141+
142+
pub mod gpio {
143+
pub enum LineDirection {
144+
In = bindings::GPIO_LINE_DIRECTION_IN as _,
145+
Out = bindings::GPIO_LINE_DIRECTION_OUT as _,
146+
}
147+
}
148+
149+
That is, the equivalent of ``GPIO_LINE_DIRECTION_IN`` would be referred to as
150+
``gpio::LineDirection::In``. In particular, it should not be named
151+
``gpio::gpio_line_direction::GPIO_LINE_DIRECTION_IN``.

0 commit comments

Comments
 (0)