Skip to contentSkip to conversation

docs: rust: add guidelines for Display and Debug

PATCH In review FUJITA Tomonori 2 participants 2 messages Nov 15 – Nov 16

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 docs: rust: add guidelines for Display and Debug

From: FUJITA Tomonori <[email protected]>

The kernel crate has no written rule about when a type should implement Display and when it should implement only Debug. This came up in the review of a patch that adds Display for Delta.

Add a section that follows the usual Rust convention, with one kernel specific point about types that correspond to C types.

---
 Documentation/rust/coding-guidelines.rst | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)
Documentation/rust/coding-guidelines.rst +22 -0
index 3198be3a6d63..90e6fdf886ea 100644
@@ -333,6 +333,28 @@ That is, the equivalent of ``GPIO_LINE_DIRECTION_IN`` would be referred to as
 ``gpio::gpio_line_direction::GPIO_LINE_DIRECTION_IN``.
 
 
+Formatting traits
+-----------------
+
+Rust kernel code follows the usual Rust convention that ``Display`` should only
+be implemented when there is a single obvious way to format the values of a type
+as text:
+
+	https://doc.rust-lang.org/core/fmt/trait.Display.html#internationalization
+
+For a type that corresponds to a C type, a format that the C side already uses
+also counts as such an obvious way, e.g. the output of a ``printk`` format
+specifier such as ``%pe``.
+
+On the other hand, some types have no single obvious format. For example, a
+quantity with a unit, such as ``Delta`` or ``Hertz``, can be printed in
+different units and with different precision.
+
+For such types, ``Debug`` should be implemented instead of ``Display``. Its
+output is for debugging, so any format that is useful for developers can be
+used. Usually ``#[derive(Debug)]`` is enough.
+
+
 Lints
 -----
 

base-commit: 23c62304dde29abe92013d85910d03a77dada35d

Signature · 1 line
2.43.0
reviewer Reviewed-by on v1 1/1
#1 lore raw
Quoted 11 lines · FUJITA Tomonori

From: FUJITA Tomonori <[email protected]>

The kernel crate has no written rule about when a type should implement Display and when it should implement only Debug. This came up in the review of a patch that adds Display for Delta.

Add a section that follows the usual Rust convention, with one kernel specific point about types that correspond to C types.

Seems sensible to me.

Best regards,
Andreas Hindborg