docs: rust: add guidelines for Display and Debug
Subsystems (2)
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
@@ -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
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