[PATCH] docs/zh_CN: add clang-format guide translation

Patch content 3 changed files

Add the Chinese clang-format guide to the dev-tools index and point thecoding guide at the translated version. Update the translation through commit faa395bcda43("docs: fix typo in clang-format documentation") Signed-off-by: Dongliang Mu <dzm91@hust.edu.cn>--- .../zh_CN/dev-tools/clang-format.rst          | 164 ++++++++++++++++++ .../translations/zh_CN/dev-tools/index.rst    |   1 + .../translations/zh_CN/process/4.Coding.rst   |   3 +- 3 files changed, 167 insertions(+), 1 deletion(-) create mode 100644 Documentation/translations/zh_CN/dev-tools/clang-format.rst diff --git a/Documentation/translations/zh_CN/dev-tools/clang-format.rst b/Documentation/translations/zh_CN/dev-tools/clang-format.rstnew file mode 100644index 000000000000..6af211275374--- /dev/null+++ b/Documentation/translations/zh_CN/dev-tools/clang-format.rst@@ -0,0 +1,164 @@+.. SPDX-License-Identifier: GPL-2.0++.. include:: ../disclaimer-zh_CN.rst++.. _clangformat_zh:++clang-format+============++``clang-format`` 是根据一套规则和启发式方法格式化 C/C++ 等代码的工具。+与多数工具一样，它并不完美，也不能覆盖所有情况，但足以提供帮助。++``clang-format`` 可用于多种用途：++  - 快速将一段代码重新排版为内核风格。移动代码、对齐或排序时尤其有用。+    参见 :ref:`clangformatreformat_zh`。++  - 发现自己维护的文件、审阅的补丁或差异中的风格问题、笔误以及可能的+    改进。参见 :ref:`clangformatreview_zh`。++  - 帮助遵循编码风格规则，尤其适合刚开始参与内核开发，或同时参与多个+    风格不同的项目的人。++配置文件是内核源码树根目录的 ``.clang-format``。其中的规则尝试接近+最常见的内核编码风格，并尽可能遵循+:doc:`内核编码风格 <../process/coding-style>`。内核各处的风格并不完全+相同，因此你可能希望针对特定子系统或目录调整默认设置。为此，可以在+子目录中再写一个 ``.clang-format`` 文件，覆盖默认设置。++这个工具早已包含在流行的 Linux 发行版软件仓库中。请在仓库中搜索+``clang-format``。也可以下载预编译的 LLVM/clang 二进制文件，或者从+以下地址获取源码自行构建：++    https://releases.llvm.org/download.html++更多信息见：++    https://clang.llvm.org/docs/ClangFormat.html++    https://clang.llvm.org/docs/ClangFormatStyleOptions.html+++.. _clangformatreview_zh:++检查文件和补丁的编码风格+------------------------++使用工具的原地修改模式，可以检查整个子系统、目录或单个文件中的编码风格+问题、笔误以及可改进之处。例如运行::++    # Make sure your working directory is clean!+    clang-format -i kernel/*.[ch]++然后查看 git diff。++统计差异中的行数，有助于改进或调整配置文件中的风格选项，也可用于测试+``clang-format`` 的新功能或新版本。++``clang-format`` 还支持读取统一格式的差异，因此可以方便地检查补丁和+git diff。参见：++    https://clang.llvm.org/docs/ClangFormat.html#script-for-patch-reformatting++若要避免 ``clang-format`` 格式化文件的某一部分，可以这样写::++    int formatted_code;+    // clang-format off+        void    unformatted_code  ;+    // clang-format on+    void formatted_code_again;++如果你正在编写新文件或担任维护者，可能会想用这种方法使文件始终与+``clang-format`` 的输出一致。但请注意，其他人可能使用不同版本的+``clang-format``，也可能根本无法使用它。因此，在它成为普遍使用的工具+之前，最好不要在内核源码中采用这种做法。+++.. _clangformatreformat_zh:++重新排版代码片段+----------------++将工具集成到文本编辑器后，只需一个快捷键就能重新排版任意代码片段+（选区）。移动代码、处理深层缩进的复杂代码以及多行宏（包括对齐反斜杠）+时，这尤其有用。++如果工具没有得到最合适的结果，仍可事后调整。不过，作为初步排版，它+通常很有帮助。++许多流行的文本编辑器都有集成支持。vim、emacs、BBEdit 和 Visual+Studio 等编辑器可能内置了相关功能。操作说明见：++    https://clang.llvm.org/docs/ClangFormat.html++Atom、Eclipse、Sublime Text、Visual Studio Code、XCode 等编辑器和+集成开发环境则可以找到现成的插件。++在这种用法下，可以考虑使用第二个 ``.clang-format`` 文件，便于调整+少量选项。参见 :ref:`clangformatextra_zh`。+++尚未支持的格式+--------------++``clang-format`` 尚不支持内核代码中常见的一些格式。这些情况很容易记住，+经常使用该工具后便能很快学会避开或忽略它们。++特别常见的情况包括：++  - 对齐的一组单行 ``#define``，例如::++        #define TRACING_MAP_BITS_DEFAULT       11+        #define TRACING_MAP_BITS_MAX           17+        #define TRACING_MAP_BITS_MIN           7++    与如下输出相比::++        #define TRACING_MAP_BITS_DEFAULT 11+        #define TRACING_MAP_BITS_MAX 17+        #define TRACING_MAP_BITS_MIN 7++  - 对齐的指定初始化项，例如::++        static const struct file_operations uprobe_events_ops = {+                .owner          = THIS_MODULE,+                .open           = probes_open,+                .read           = seq_read,+                .llseek         = seq_lseek,+                .release        = seq_release,+                .write          = probes_write,+        };++    与如下输出相比::++        static const struct file_operations uprobe_events_ops = {+                .owner = THIS_MODULE,+                .open = probes_open,+                .read = seq_read,+                .llseek = seq_lseek,+                .release = seq_release,+                .write = probes_write,+        };+++.. _clangformatextra_zh:++额外功能和选项+--------------++配置文件默认未启用某些功能或风格选项，以尽量减少格式化输出与当前代码+的差异，从而便于检查整份文件的风格以及差异和补丁。++在其他情况下，例如特定子系统、目录或文件，内核风格可能有所不同，+启用部分选项反而能更接近当地的风格。++例如：++  - 对齐赋值语句（``AlignConsecutiveAssignments``）。+  - 对齐声明（``AlignConsecutiveDeclarations``）。+  - 重新排版注释中的文本（``ReflowComments``）。+  - 对 ``#include`` 排序（``SortIncludes``）。++这些选项通常更适合重新排版代码片段，而非整份文件。可以另建一个+``.clang-format`` 文件，在编辑器或集成开发环境中使用它。diff --git a/Documentation/translations/zh_CN/dev-tools/index.rst b/Documentation/translations/zh_CN/dev-tools/index.rstindex 7b37194217b0..cf8d7d71904b 100644--- a/Documentation/translations/zh_CN/dev-tools/index.rst+++ b/Documentation/translations/zh_CN/dev-tools/index.rst@@ -19,6 +19,7 @@ Documentation/translations/zh_CN/dev-tools/testing-overview.rst    :maxdepth: 2     testing-overview+   clang-format    sparse    kcov    kcsandiff --git a/Documentation/translations/zh_CN/process/4.Coding.rst b/Documentation/translations/zh_CN/process/4.Coding.rstindex a00ad5d6b81e..2fa79e496167 100644--- a/Documentation/translations/zh_CN/process/4.Coding.rst+++ b/Documentation/translations/zh_CN/process/4.Coding.rst@@ -54,7 +54,8 @@ 注意您还可以使用 ``clang-format`` 工具来帮助您处理这些规则，快速自动重新格式 化部分代码，和审阅完整的文件以发现代码样式错误、拼写错误和可能的改进。它还 可以方便地排序 ``#includes`` 、对齐变量/宏、重排文本和其他类似任务。有关详细-信息，请参阅文档 :ref:`Documentation/dev-tools/clang-format.rst <clangformat>`+信息，请参阅+:ref:`Documentation/translations/zh_CN/dev-tools/clang-format.rst <clangformat_zh>`。  抽象层 ******-- 2.51.0