Commit 5d88f98b authored by Vincent Woltmann's avatar Vincent Woltmann Committed by Miguel Ojeda

docs: rust: remove unintended blockquote in Coding Guidelines

An unordered list in coding-guidelines.rst was indented, producing
a blockquote around it and making it look more indented than expected.
Remove the indentation to only output an unordered list.
Reported-by: default avatarMiguel Ojeda <ojeda@kernel.org>
Closes: https://github.com/Rust-for-Linux/linux/issues/1063
Fixes: d07479b2 ("docs: add Rust documentation")
Signed-off-by: default avatarVincent Woltmann <vincent@woltmann.art>
Link: https://lore.kernel.org/r/20240816200339.2495875-1-vincent@woltmann.art
[ Reworded title. - Miguel ]
Signed-off-by: default avatarMiguel Ojeda <ojeda@kernel.org>
parent fd764e74
...@@ -145,32 +145,32 @@ This is how a well-documented Rust function may look like: ...@@ -145,32 +145,32 @@ This is how a well-documented Rust function may look like:
This example showcases a few ``rustdoc`` features and some conventions followed This example showcases a few ``rustdoc`` features and some conventions followed
in the kernel: in the kernel:
- The first paragraph must be a single sentence briefly describing what - The first paragraph must be a single sentence briefly describing what
the documented item does. Further explanations must go in extra paragraphs. the documented item does. Further explanations must go in extra paragraphs.
- Unsafe functions must document their safety preconditions under - Unsafe functions must document their safety preconditions under
a ``# Safety`` section. a ``# Safety`` section.
- While not shown here, if a function may panic, the conditions under which - While not shown here, if a function may panic, the conditions under which
that happens must be described under a ``# Panics`` section. that happens must be described under a ``# Panics`` section.
Please note that panicking should be very rare and used only with a good Please note that panicking should be very rare and used only with a good
reason. In almost all cases, a fallible approach should be used, typically reason. In almost all cases, a fallible approach should be used, typically
returning a ``Result``. returning a ``Result``.
- If providing examples of usage would help readers, they must be written in - If providing examples of usage would help readers, they must be written in
a section called ``# Examples``. a section called ``# Examples``.
- Rust items (functions, types, constants...) must be linked appropriately - Rust items (functions, types, constants...) must be linked appropriately
(``rustdoc`` will create a link automatically). (``rustdoc`` will create a link automatically).
- Any ``unsafe`` block must be preceded by a ``// SAFETY:`` comment - Any ``unsafe`` block must be preceded by a ``// SAFETY:`` comment
describing why the code inside is sound. describing why the code inside is sound.
While sometimes the reason might look trivial and therefore unneeded, While sometimes the reason might look trivial and therefore unneeded,
writing these comments is not just a good way of documenting what has been 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 taken into account, but most importantly, it provides a way to know that
there are no *extra* implicit constraints. there are no *extra* implicit constraints.
To learn more about how to write documentation for Rust and extra features, To learn more about how to write documentation for Rust and extra features,
please take a look at the ``rustdoc`` book at: please take a look at the ``rustdoc`` book at:
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment