Lines Matching +full:block +full:- +full:comment

1 .. SPDX-License-Identifier: GPL-2.0
10 ------------------
37 Like ``clang-format`` for the rest of the kernel, ``rustfmt`` works on
48 .. code-block:: rust
60 .. code-block:: rust
77 The trailing empty comment allows to preserve this formatting. Not only that,
78 ``rustfmt`` will actually reformat imports vertically when the empty comment is
82 .. code-block:: rust
93 The trailing empty comment works for nested imports, as shown above, as well as
94 for single item imports -- this can be useful to minimize diffs within patch
97 .. code-block:: rust
103 The trailing empty comment works in any of the lines within the braces, but it
106 the comment several times within a patch series due to changes in the list.
114 empty comment. Thus, at some point, the goal is to remove those comments.
118 --------
126 .. code-block:: rust
135 .. code-block:: rust
143 For instance, for a ``TODO`` list or to comment on the documentation itself.
148 .. code-block:: rust
159 	pub fn f(x: i32) -> Foo {
169 .. code-block:: rust
176 before every ``unsafe`` block, and they explain why the code inside the block is
179 .. code-block:: rust
193 ------------------
195 Rust kernel code is not documented like C kernel code (i.e. via kernel-doc).
204 This is how a well-documented Rust function may look like:
206 .. code-block:: rust
215 	/// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html
223 	pub unsafe fn unwrap_unchecked(self) -> T {
235 - The first paragraph must be a single sentence briefly describing what
238 - Unsafe functions must document their safety preconditions under
241 - While not shown here, if a function may panic, the conditions under which
248 - If providing examples of usage would help readers, they must be written in
251 - Rust items (functions, types, constants...) must be linked appropriately
254 - Any ``unsafe`` block must be preceded by a ``// SAFETY:`` comment
265 	https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html
270 .. code-block:: rust
276 .. code-block:: rust
282 -----------
286 not use the aliases from ``core::ffi`` -- they may not map to the correct types.
291 .. code-block:: rust
293 	fn f(p: *const c_char) -> c_int {
299 ------
303 	https://rust-lang.github.io/api-guidelines/naming.html
315 .. code-block:: c
322 .. code-block:: rust
337 -----
341 function, module, block, etc.
346 .. code-block:: c
349 	#pragma GCC diagnostic ignored "-Wunused-function"
359 .. code-block:: rust
374 .. code-block:: rust
382 	 --> x.rs:3:10
392 - Temporary attributes added while developing.
394 - Improvements in lints in the compiler, Clippy or custom tools which may
397 - When the lint is not needed anymore because it was expected that it would be
405 - Conditional compilation triggers the warning in some cases but not others.
412 - Inside macros, when the different invocations may create expanded code that
415 - When code may trigger a warning for some architectures but not others, such
420 .. code-block:: rust
432 .. code-block:: rust
443 configuration. Therefore, in cases like this, we cannot use ``expect`` as-is.
447 .. code-block:: rust
459 .. code-block:: rust
475 triggered due to non-local changes (such as ``dead_code``).
479 	https://doc.rust-lang.org/stable/reference/attributes/diagnostics.html
482 --------------
487 	https://rust.docs.kernel.org/kernel/error/type.Result.html#error-codes-in-c-and-rust