Documentation/translations/zh_CN/rust/coding-guidelines.rst

Source file repositories/reference/linux-study-clean/Documentation/translations/zh_CN/rust/coding-guidelines.rst

File Facts

System
Linux kernel
Corpus path
Documentation/translations/zh_CN/rust/coding-guidelines.rst
Extension
.rst
Size
14330 bytes
Lines
439
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

fn f() {}

一种特殊的注释是 ``// SAFETY:`` 注释。这些注释必须出现在每个 ``unsafe`` 块之前，它们
解释了为什么该块内的代码是正确/健全的，即为什么它在任何情况下都不会触发未定义行为，例如:

.. code-block:: rust

	// SAFETY: `p` is valid by the safety requirements.
	unsafe { *p = 0; }

``// SAFETY:`` 注释不能与代码文档中的 ``# Safety`` 部分相混淆。 ``# Safety`` 部
分指定了（函数）调用者或（特性）实现者需要遵守的契约。
``// SAFETY:`` 注释显示了为什么一个（函数）调用者或（特性）实现者实际上尊重了
``# Safety`` 部分或语言参考中的前提条件。


代码文档
--------

Rust内核代码不像C内核代码那样被记录下来（即通过kernel-doc）。取而代之的是用于记录Rust
代码的常用系统：rustdoc工具，它使用Markdown（一种轻量级的标记语言）。

要学习Markdown，外面有很多指南。例如：

https://commonmark.org/help/

一个记录良好的Rust函数可能是这样的:

.. code-block:: rust

	/// Returns the contained [`Some`] value, consuming the `self` value,
	/// without checking that the value is not [`None`].
	///
	/// # Safety
	///
	/// Calling this method on [`None`] is *[undefined behavior]*.
	///
	/// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html
	///
	/// # Examples
	///
	/// ```
	/// let x = Some("air");
	/// assert_eq!(unsafe { x.unwrap_unchecked() }, "air");
	/// ```
	pub unsafe fn unwrap_unchecked(self) -> T {
	    match self {
	        Some(val) => val,

	        // SAFETY: The safety contract must be upheld by the caller.
	        None => unsafe { hint::unreachable_unchecked() },
	    }
	}

这个例子展示了一些 ``rustdoc`` 的特性和内核中遵循的一些惯例:

- 第一段必须是一个简单的句子，简要地描述被记录的项目的作用。进一步的解释必须放在额
  外的段落中。

- 不安全的函数必须在 ``# Safety`` 部分记录其安全前提条件。

- 虽然这里没有显示，但如果一个函数可能会恐慌，那么必须在 ``# Panics`` 部分描述发
  生这种情况的条件。

  请注意，恐慌应该是非常少见的，只有在有充分理由的情况下才会使用。几乎在所有的情况下，
  都应该使用一个可失败的方法，通常是返回一个 ``Result``。

- 如果提供使用实例对读者有帮助的话，必须写在一个叫做``# Examples``的部分。

- Rust项目（函数、类型、常量……）必须有适当的链接(``rustdoc`` 会自动创建一个

Annotation

Implementation Notes