@@ -145,32 +145,32 @@ This is how a well-documented Rust function may look like:
145
145
This example showcases a few ``rustdoc `` features and some conventions followed
146
146
in the kernel:
147
147
148
- - The first paragraph must be a single sentence briefly describing what
149
- the documented item does. Further explanations must go in extra paragraphs.
148
+ - The first paragraph must be a single sentence briefly describing what
149
+ the documented item does. Further explanations must go in extra paragraphs.
150
150
151
- - Unsafe functions must document their safety preconditions under
152
- a ``# Safety `` section.
151
+ - Unsafe functions must document their safety preconditions under
152
+ a ``# Safety `` section.
153
153
154
- - While not shown here, if a function may panic, the conditions under which
155
- that happens must be described under a ``# Panics `` section.
154
+ - While not shown here, if a function may panic, the conditions under which
155
+ that happens must be described under a ``# Panics `` section.
156
156
157
- Please note that panicking should be very rare and used only with a good
158
- reason. In almost all cases, a fallible approach should be used, typically
159
- returning a ``Result ``.
157
+ Please note that panicking should be very rare and used only with a good
158
+ reason. In almost all cases, a fallible approach should be used, typically
159
+ returning a ``Result ``.
160
160
161
- - If providing examples of usage would help readers, they must be written in
162
- a section called ``# Examples ``.
161
+ - If providing examples of usage would help readers, they must be written in
162
+ a section called ``# Examples ``.
163
163
164
- - Rust items (functions, types, constants...) must be linked appropriately
165
- (``rustdoc `` will create a link automatically).
164
+ - Rust items (functions, types, constants...) must be linked appropriately
165
+ (``rustdoc `` will create a link automatically).
166
166
167
- - Any ``unsafe `` block must be preceded by a ``// SAFETY: `` comment
168
- describing why the code inside is sound.
167
+ - Any ``unsafe `` block must be preceded by a ``// SAFETY: `` comment
168
+ describing why the code inside is sound.
169
169
170
- While sometimes the reason might look trivial and therefore unneeded,
171
- writing these comments is not just a good way of documenting what has been
172
- taken into account, but most importantly, it provides a way to know that
173
- there are no *extra * implicit constraints.
170
+ While sometimes the reason might look trivial and therefore unneeded,
171
+ writing these comments is not just a good way of documenting what has been
172
+ taken into account, but most importantly, it provides a way to know that
173
+ there are no *extra * implicit constraints.
174
174
175
175
To learn more about how to write documentation for Rust and extra features,
176
176
please take a look at the ``rustdoc `` book at:
0 commit comments