Merge pull request Rust-Coding-Guidelines#9 from Milittle/main

[Translate]:Code-Style/2.3 Code Comments:P.CMT.[03, 04. 05], G.GMT.[01, 02, 03]

Author: ZhangHanDong

src/safe-guides/code_style/comments/G.CMT.01.md

@@ -1 +1,44 @@
-# G.CMT.01 在公开的返回Result类型的函数文档中增加 Error 注释
+# G.CMT.01 Error comments need to added the documentation of functions that return `Result` types in the public
+
+**[Level]** Suggestion
+
+**[Description]**
+
+In the public (pub) documentation of functions that return `Result` types, it is recommended to add `# Error` comments to explain what scenarios the function will return what kind of error type, so that users can easily handle errors.
+
+Description: This rule can be detected by cargo clippy, but it does not warn by default.
+
+**[Bad Case]**
+
+```rust
+#![warn(clippy::missing_errors_doc)]
+
+use std::io;
+// Bad： Clippy will be warned "warning: docs for function returning `Result` missing `# Errors` section"
+pub fn read(filename: String) -> io::Result<String> {
+    unimplemented!();
+}
+```
+
+**[Good Case]**
+
+```rust
+#![warn(clippy::missing_errors_doc)]
+
+use std::io;
+// Good：adding normatives Errors documentation comments
+
+/// # Errors
+///
+/// Will return `Err` if `filename` does not exist or the user does not have
+/// permission to read it.
+pub fn read(filename: String) -> io::Result<String> {
+    unimplemented!();
+}
+```
+
+**[Lint detection]**
+
+| Lint name                                                                                            | Clippy detectable | Rustc detectable | Lint Group | Default level |
+| ---------------------------------------------------------------------------------------------------- | ----------------- | ---------------- | ---------- | ------------- |
+| [missing_errors_doc ](https://rust-lang.github.io/rust-clippy/master/index.html#missing_errors_doc ) | yes               | no               | Style      | allow         |

src/safe-guides/code_style/comments/G.CMT.02.md

@@ -1 +1,50 @@
-# G.CMT.02 如果公开的API在某些情况下会发生Panic，则相应文档中需增加 Panic 注释
+# G.CMT.02 If a Panic occurs under certain circumstances in the public API, add a Panic comment to the corresponding document
+
+**[Level]** Requirements
+
+**[Description]**
+
+In the public (pub) function documentation, it is recommended to add `# Panic` comments to explain under what conditions the function will Panic, so that users can pre-process it.
+
+Description: This rule is detected by cargo clippy. It does not warn by default.
+
+**[Bad Case]**
+
+```rust
+#![warn(clippy::missing_panics_doc)]
+
+// Bad：If do not add Panic relevant comments.`Clippy` will raise error: "warning: docs for function which may panic missing `# Panics` section"。
+pub fn divide_by(x: i32, y: i32) -> i32 {
+    if y == 0 {
+        panic!("Cannot divide by 0")
+    } else {
+        x / y
+    }
+}
+```
+
+**[Good Case]**
+
+```rust
+#![warn(clippy::missing_panics_doc)]
+
+// Good：Added Panic comments
+/// # Panics
+///
+/// Will panic if y is 0
+pub fn divide_by(x: i32, y: i32) -> i32 {
+    if y == 0 {
+        panic!("Cannot divide by 0")
+    } else {
+        x / y
+    }
+}
+```
+
+**[Lint detect]**
+
+| Lint name                                                                                            | Clippy detectable | Rustc detectable | Lint Group | Default level |
+| ---------------------------------------------------------------------------------------------------- | ----------------- | ---------------- | ---------- | ------------- |
+| [missing_panics_doc ](https://rust-lang.github.io/rust-clippy/master/index.html#missing_panics_doc ) | yes               | no               | Style      | allow         |
+
+Default is `allow`，But this pricipal need to be set `#![warn(clippy::missing_panics_doc)]`。

src/safe-guides/code_style/comments/G.CMT.03.md

@@ -1 +1,56 @@
-# G.CMT.03 在文档注释中要使用空格代替 tab
+# G.CMT.03 Use spaces in document comments instead of tabs
+
+**[Level]** Suggestion
+
+**[Description]**
+
+Rust code style promotes the use of **four spaces** instead of tabs, and **four spaces** should be used consistently in the documentation comments.
+
+**[Bad Case]**
+
+Tab is used in the following document comments.
+
+```rust
+// Bad：Tab indentation is used in document comments
+///
+/// Struct to hold two strings:
+/// 	- first		one
+/// 	- second	one
+pub struct DoubleString {
+   ///
+   /// 	- First String:
+   /// 		- needs to be inside here
+   first_string: String,
+   ///
+   /// 	- Second String:
+   /// 		- needs to be inside here
+   second_string: String,
+}
+```
+
+**[Good Case]**
+
+```rust
+// Good：Four spaces indentation is used in document comments
+///
+/// Struct to hold two strings:
+///     - first        one
+///     - second    one
+pub struct DoubleString {
+   ///
+   ///     - First String:
+   ///         - needs to be inside here
+   first_string: String,
+   ///
+   ///     - Second String:
+   ///         - needs to be inside here
+   second_string: String,
+}
+```
+
+**[Lint detect]**
+
+| Lint name                                                                                                | Clippy detectable | Rustc detectable | Lint Group | Default level |
+| -------------------------------------------------------------------------------------------------------- | ----------------- | ---------------- | ---------- | ------------- |
+| [tabs_in_doc_comments ](https://rust-lang.github.io/rust-clippy/master/index.html#tabs_in_doc_comments ) | yes               | no               | Style      | warn          |
+s

src/safe-guides/code_style/comments/P.CMT.03.md

@@ -1 +1,56 @@
-# P.CMT.03 使用行注释而避免使用块注释
+# P.CMT.03 Use line comments and avoid block comments
+
+**[Description]**
+
+Try to use line comments (`//` or `///`) rather than block comments. This is a convention in the Rust community.
+
+For documentation comments, use `//! `, in other cases `///` is better.
+
+Note: `#! [doc]` and `#[doc]` have a special role in simplifying document comments, and it is not necessary to force them into `//! ` or `//`.
+
+**[Bad Case]**
+
+```rust
+// Bad
+
+/*
+ * Wait for the main task to return, and set the process error code
+ * appropriately.
+ */
+mod tests {
+    //! This module contains tests
+
+    // ...
+}
+```
+
+**[Good Case]**
+
+When `normalize_comments = true`:
+
+```rust
+// Good
+
+// Wait for the main task to return, and set the process error code
+// appropriately.
+
+// Good
+// When defining modules using the `mod` keyword, 
+// it is better to use `///` on top of `mod`.
+
+/// This module contains tests
+mod tests {
+    // ...
+}
+
+// Good
+#[doc = "Example item documentation"]
+pub enum Foo {}
+```
+
+**【rustfmt configuration】**
+
+| Parameter                                                                                    | Optional                         | Stable or not | Description                                                         |
+| -------------------------------------------------------------------------------------------- | -------------------------------- | ------------- | ------------------------------------------------------------------- |
+| [`normalize_comments`](https://rust-lang.github.io/rustfmt/?#normalize_comments)             | false(default) true(suggestionn) | No            | Convert the `/**/` comment to `/`                                   |
+| [`normalize_doc_attributes`](https://rust-lang.github.io/rustfmt/?#normalize_doc_attributes) | false(default)                   | No            | Convert the `#! [doc]` and `#[doc]` annotations to `//! ` and `///` |

src/safe-guides/code_style/comments/P.CMT.04.md

@@ -1 +1,46 @@
-# P.CMT.04 文件头注释包含版权说明
+# P.CMT.04 File header comments include a copyright notice
+
+**[Description]**
+
+File header (i.e., module-level) comments should include the copyright notice first. If additional content needs to be added to the file header comments, it can be added under the copyright notice.
+
+May include:
+
+1. A description of the function of the document.
+2. Author.
+3. Creation date and last modification date.
+4. Notes.
+5. Open source license (e.g., Apache 2.0, BSD, LGPL, GPL).
+6. Other.
+
+The format of the copyright notice is as follows:
+
+- 中文版：`版权所有（c）XXX 技术有限公司 2015-2022`。
+- English version: `Copyright (c) XXX Technologies Co. Ltd. 2015-2022. All rights reserved. Licensed under Apache-2.0.`
+
+Its content can be adjusted to participate in the following detailed description:
+
+- `2015-2022` can be modified as needed. 2015 is the year the file was first created and 2022 is the year the file was last modified. It is possible to write only one creation year, so that the copyright notice does not need to be changed if the file is modified frequently.
+- For internal use, there is no need to add `All rights reserved`.
+- `Licensed under Apache-2.0.`, if it is open source then you can add the license statement.
+
+Caution when writing copyright notes:
+
+- Copyright notes should be written from the top of the file header.
+- The header comment should contain the "copyright notice" first, followed by the rest of the content.
+- Optional content should be added as needed to avoid empty formatting without content.
+- Maintain uniform formatting, either by the project or by the larger context.
+- Maintain a neat layout, with line breaks aligned.
+
+**[Good Case]**
+
+```rust
+// Good
+// 版权所有（c）XXX 技术有限公司 2015-2022。
+
+// Or
+
+// Good
+// Copyright (c) XXX Technologies Co.Ltd. 2015-2022. 
+// All rights reserved. Licensed under Apache-2.0.
+```

src/safe-guides/code_style/comments/P.CMT.05.md

@@ -1 +1,25 @@
-# P.CMT.05 在注释中使用 FIXME 和 TODO 来帮助任务协作
+# P.CMT.05 Use `FIXME` and `TODO` in comments to help with task collaboration
+
+**[Description]**
+
+Collaboration can be facilitated by turning on `FIXME` and `TODO` in the comments.
+
+Note: This entry is not suitable for use with `rustfmt` related configuration items `report_fixme` and `report_todo`, which have been removed in `rustfmt` v2.0.
+
+**[Good Case]**
+
+```rust
+// Good
+// TODO(calebcartwright): consider enabling box_patterns feature gate
+fn annotation_type_for_level(level: Level) -> AnnotationType {
+    match level {
+        Level::Bug | Level::Fatal | Level::Error => AnnotationType::Error,
+        Level::Warning => AnnotationType::Warning,
+        Level::Note => AnnotationType::Note,
+        Level::Help => AnnotationType::Help,
+        // FIXME(#59346): Not sure how to map these two levels
+        Level::Cancelled | Level::FailureNote => AnnotationType::Error,
+        Level::Allow => panic!("Should not call with Allow"),
+    }
+}
+```