update (#105)

* V 0.3

* V0.3: modify README

* update Version to 0.3

* add code example for P.SEC.01

* modify P.SEC.01

* 3.30 review

* update

Author: ZhangHanDong

src/SUMMARY.md

@@ -37,8 +37,8 @@
         - [P.CMT.01](./safe-guides/code_style/comments/P.CMT.01.md)
         - [P.CMT.02](./safe-guides/code_style/comments/P.CMT.02.md)
         - [P.CMT.03](./safe-guides/code_style/comments/P.CMT.03.md)
-        - [P.CMT.04](./safe-guides/code_style/comments/G.CMT.04.md)
-        - [P.CMT.05](./safe-guides/code_style/comments/G.CMT.05.md)
+        - [P.CMT.04](./safe-guides/code_style/comments/P.CMT.04.md)
+        - [P.CMT.05](./safe-guides/code_style/comments/P.CMT.05.md)
         - [G.CMT.01](./safe-guides/code_style/comments/G.CMT.01.md)
         - [G.CMT.02](./safe-guides/code_style/comments/G.CMT.02.md)
         - [G.CMT.03](./safe-guides/code_style/comments/G.CMT.03.md)

src/safe-guides/Appendix/templates/clippy.toml.md

@@ -169,3 +169,16 @@ Embark 也在跟踪和推动在 Cargo 中支持 Lint 配置的功能，相关 is
 - [Be able to disable/enable Clippy lints globally](https://github.com/EmbarkStudios/rust-ecosystem/issues/22)
 - [Support defining enabled and disabled lints in a configuration file](https://github.com/rust-lang/cargo/issues/5034)
 - [[Roadmap] Configuration file for lints](https://github.com/rust-lang/rust-clippy/issues/6625)
+
+## 代码生成相关 clippy 配置
+
+和 C 语言绑定代码生成，避免clippy 警告，相关配置可参考：
+
+```rust
+// Generated by gir (https://github.com/gtk-rs/gir @ 5bbf6cb)
+// from ../gir-files (@ 8e47c67)
+// DO NOT EDIT
+
+#![allow(non_camel_case_types, non_upper_case_globals, non_snake_case)]
+#![allow(clippy::approx_constant, clippy::type_complexity, clippy::unreadable_literal, clippy::upper_case_acronyms)]
+```

src/safe-guides/code_style/comments.md

@@ -8,7 +8,7 @@
 ## 列表
 
 - [P.CMT.01 代码能做到自注释，文档要干练简洁](./comments/P.CMT.01.md)
-- [P.CMT.02 注释应该有一定宽度限制](./comments/P.CMT.02.md)
+- [P.CMT.02 注释应该有宽度限制](./comments/P.CMT.02.md)
 - [P.CMT.03 使用行注释而避免使用块注释](./comments/P.CMT.03.md)
 - [P.CMT.04 文件头注释包含版权说明](./comments/P.CMT.04.md)
 - [P.CMT.05 在注释中使用 FIXME 和 TODO 来帮助任务协作](./comments/P.CMT.05.md)

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

@@ -1,17 +1,21 @@
-## G.CMT.01 在 公开的返回`Result`类型返回的函数文档中增加 Error 注释
+## G.CMT.01 在公开的返回`Result`类型的函数文档中增加 Error 注释
 
 **【级别】** 建议
 
 **【描述】**
 
-在公开（pub）的返回`Result`类型函数文档中，建议增加 `# Error` 注释来解释什么场景下该函数会返回什么样的错误类型，方便用户处理错误。
+在公开（pub）的返回`Result`类型的函数文档中，建议增加 `# Error` 注释来解释什么场景下该函数会返回什么样的错误类型，方便用户处理错误。
 
-说明： 该规则通过 cargo clippy 来检测。默认不会警告。
+说明： 该规则可以通过 cargo clippy 来检测，但默认不会警告。
 
 **【反例】**
 
+
 ```rust
-# use std::io;
+#![warn(clippy::missing_errors_doc)]
+
+use std::io;
+// 不符合： Clippy 会警告 "warning: docs for function returning `Result` missing `# Errors` section"
 pub fn read(filename: String) -> io::Result<String> {
     unimplemented!();
 }
@@ -20,7 +24,11 @@ pub fn read(filename: String) -> io::Result<String> {
 **【正例】**
 
 ```rust
-# use std::io;
+#![warn(clippy::missing_errors_doc)]
+
+use std::io;
+// 符合：增加了规范的 Errors 文档注释
+
 /// # Errors
 ///
 /// Will return `Err` if `filename` does not exist or the user does not have

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

@@ -11,6 +11,9 @@
 **【反例】**
 
 ```rust
+#![warn(clippy::missing_panics_doc)]
+
+// 不符合：没有添加 Panic 相关的文档注释，Clippy会报错 "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")
@@ -23,6 +26,9 @@ pub fn divide_by(x: i32, y: i32) -> i32 {
 **【正例】**
 
 ```rust
+#![warn(clippy::missing_panics_doc)]
+
+// 符合：增加了规范的 Panic 注释
 /// # Panics
 ///
 /// Will panic if y is 0
@@ -39,4 +45,6 @@ pub fn divide_by(x: i32, y: i32) -> i32 {
 
 | lint name | Clippy 可检测 | Rustc 可检测 | Lint Group | 默认 level |
 | ------ | ---- | --------- | ------ | ------ | 
-| [missing_panics_doc ](https://rust-lang.github.io/rust-clippy/master/index.html#missing_panics_doc ) | yes| no | Style | allow | 
+| [missing_panics_doc ](https://rust-lang.github.io/rust-clippy/master/index.html#missing_panics_doc ) | yes| no | Style | allow | 
+
+默认为 `allow`，但是此规则需要设置`#![warn(clippy::missing_panics_doc)]`。

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

@@ -11,6 +11,7 @@ Rust 代码风格中提倡使用**四个空格**代替tab，在文档注释中
 下面文档注释中使用了 tab。
 
 ```rust
+// 不符合：文档注释中使用了 tab 缩进
 ///
 /// Struct to hold two strings:
 /// 	- first		one
@@ -30,6 +31,7 @@ pub struct DoubleString {
 **【正例】**
 
 ```rust
+// 符合：文档注释中使用了四个空格缩进
 ///
 /// Struct to hold two strings:
 ///     - first        one
@@ -51,5 +53,3 @@ pub struct DoubleString {
 | lint name                                                    | Clippy 可检测 | Rustc 可检测 | Lint Group | 默认 level |
 | ------------------------------------------------------------ | ------------- | ------------ | ---------- | ---------- |
 | [tabs_in_doc_comments ](https://rust-lang.github.io/rust-clippy/master/index.html#tabs_in_doc_comments ) | yes           | no           | Style      | warn       |
-
----

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

@@ -22,6 +22,8 @@
 模块级文档，来自于 Rust 标准库`std::vec`：
 
 ```rust
+// 符合
+
 //! # The Rust core allocation and collections library
 //!
 //! This library provides smart pointers and collections for managing
@@ -42,20 +44,22 @@
 普通文档注释示例，来自标准库`Vec::new`方法：
 
 ```rust
-    /// Constructs a new, empty `Vec<T>`.
-    ///
-    /// The vector will not allocate until elements are pushed onto it.
-    ///
-    /// # Examples
-    ///
-    /// ```
-    /// # #![allow(unused_mut)]
-    /// let mut vec: Vec<i32> = Vec::new();
-    /// ```
-    #[inline]
-    #[rustc_const_stable(feature = "const_vec_new", since = "1.39.0")]
-    #[stable(feature = "rust1", since = "1.0.0")]
-    pub const fn new() -> Self {
-        Vec { buf: RawVec::NEW, len: 0 }
-    }
+// 符合
+
+/// Constructs a new, empty `Vec<T>`.
+///
+/// The vector will not allocate until elements are pushed onto it.
+///
+/// # Examples
+///
+/// ```
+/// # #![allow(unused_mut)]
+/// let mut vec: Vec<i32> = Vec::new();
+/// ```
+#[inline]
+#[rustc_const_stable(feature = "const_vec_new", since = "1.39.0")]
+#[stable(feature = "rust1", since = "1.0.0")]
+pub const fn new() -> Self {
+    Vec { buf: RawVec::NEW, len: 0 }
+}
 ```

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

@@ -1,14 +1,17 @@
-## P.CMT.02  注释应该有一定宽度限制
+## P.CMT.02  注释应该有宽度限制
 
 **【描述】**
 
-每行注释的宽度不能过长，需要设置一定的宽度，有助于提升可读性。`comment_width`可配合 `wrap_comments` 将超过宽度限制的注释自动分割为多行。
+每行注释的宽度不能过长，需要设置一定的宽度，不超过120，有助于提升可读性。
 
-注意：`use_small_heuristics`配置项并不包括`comment_width`。
+`rustfmt`中通过`comment_width`配合 `wrap_comments` 配置项，可将超过宽度限制的注释自动分割为多行。
+
+注意：`rustfmt`的 `use_small_heuristics`配置项并不包括`comment_width`。
 
 **【反例】**
 
 ```rust
+// 不符合
 // Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
 ```
 
@@ -19,6 +22,7 @@
 注意：这里 `wrap_comments`并未使用默认值，需要配置为 true。
 
 ```rust
+// 符合
 // Lorem ipsum dolor sit amet, consectetur adipiscing elit,
 // sed do eiusmod tempor incididunt ut labore et dolore
 // magna aliqua. Ut enim ad minim veniam, quis nostrud
@@ -28,10 +32,6 @@
 
 **【rustfmt 配置】**
 
-此规则 Clippy 不可检测，由 rustfmt 自动格式化。
-
-rustfmt 配置：
-
 | 对应选项 | 可选值 | 是否 stable | 说明 |
 | ------ | ---- | ---- | ---- |
 | [`comment_width`](https://rust-lang.github.io/rustfmt/?#comment_width) | 80（默认） | No|  指定一行注释允许的最大宽度 |