update

content/3/chapter10/0.tex

@@ -1,10 +1,10 @@
 高质量的代码不仅要写得很好、工作良好、测试良好，而且还要有完整的文档记录。文档允许我们共享可能丢失的信息，描绘更大的图景，提供上下文，揭示意图，并最终让外部用户和维护人员更容易理解代码或项目。
 
-还记得上次加入的新项目么？在迷宫般的目录和文件中迷失了好几个小时吗?这本可以避免的。真正优秀的文档可以让新手在几秒钟内找到他们想要的代码行。遗憾的是，缺少文档的问题常常被掩盖起来。这并不奇怪，这需要很多技巧，我们中的许多人并不擅长制作文档。最重要的是，文档和代码工作是分离的，除非制定了严格的更新和审查流程，否则很容易忘记更新文档。
+还记得上次加入的新项目么？在迷宫般的目录和文件中迷失了好几个小时吗?这本可以避免的。真正优秀的文档可以让新手在几秒钟内找到他们想要的代码行。遗憾的是，缺少文档的问题常常被掩盖起来。这并不奇怪，这需要很多技巧，许多人并不擅长制作文档。最重要的是，文档和代码工作是分离的，除非制定了严格的更新和审查流程，否则很容易忘记更新文档。
 
 有些团队(为了节省时间或受到管理人员的鼓励)遵循编写“自文档化代码”的实践。通过为文件名、函数、变量等选择有意义的、可读的标识符，从而避免记录的繁琐工作。虽然好的命名习惯是绝对正确的，但其不能取代文档。即使是最好的函数签名也不能保证传递所有必要的信息——例如，int removeduplates ();是非常描述性的，但并没有揭示返回的是什么!可能是找到的副本数量，剩下的物品数量，或者其他东西——这并不确定。记住:天下没有免费的午餐。
 
-为了简化工作，专业人员使用自动文档生成器，它可以分析源文件中的代码和注释，以多种不同格式生成全面的文档。在CMake项目中添加这样的生成器非常简单——来看看文档是怎么做!
+为了简化工作，专业人员使用自动文档生成器，它可以分析源文件中的代码和注释，以多种不同格式生成全面的文档。在CMake项目中添加这样的生成器非常简单——来看看文档是怎么生成!
 
 本章中，我们将讨论以下主题:
 

content/3/chapter10/2.tex

@@ -1,4 +1,4 @@
-可以从C++源码生成文档的成熟和流行的工具是Doxygen。当我说“建立”的时候，我指的是:第一个版本是由Dimitri van Heesch在1997年10月发布的。从那时起，其存储库(\url{https://github.com/doxygen/doxygen})就得到了180多个贡献者的积极支持。
+可以从C++源码生成文档的成熟和流行的工具是Doxygen，其第一个版本是由Dimitri van Heesch在1997年10月发布的。从那时起，其存储库(\url{https://github.com/doxygen/doxygen})就得到了180多个贡献者的积极支持。
 
 Doxygen可以生成以下格式的文档:
 
@@ -25,9 +25,9 @@
 Microsoft课编译HTML帮助(CHM)
 \end{itemize}
 
-若用Doxygen指定的格式提供额外信息的注释装饰代码，其将解析为丰富的输出文件。此外，还将分析代码结构以生成有用的图表。后者是可选的，因为需要Graphviz工具(\url{https://graphviz.org/})。
+若用Doxygen指定的格式提供额外信息的注释装饰代码，其将解析为丰富的输出文件，还可以分析代码结构以生成有用的图表。后者是可选的，并且需要Graphviz工具(\url{https://graphviz.org/})支持。
 
-开发人员首先应该回答以下问题:项目的用户是直接获得文档，还是自己生成文档(也许是在从源码构建时)?第一个选项意味着文档是随二进制文件一起提供的，可以在线获得，或者(不那么优雅地)与源代码一起检入存储库。
+开发人员首先应该回答以下问题:项目的用户是直接获得文档，还是自己生成文档(也许是在从源码构建时)?第一个选项意味着文档是随二进制文件一起提供的，可以在线获得，或者(不那么优雅地)与源代码一起存入存储库。
 
 答案很重要，因为若希望用户在构建过程中生成文档，他们将需要系统中存在的依赖项。这不是一个太大的问题，因为Doxygen可以通过大多数包管理器(以及Graphviz)获得，所有需要的只是一个简单的命令，例如Debian的这个命令:
 
@@ -37,9 +37,9 @@
 
 Windows上也有可用的二进制文件(查看该项目的网站)。
 
-为用户生成文档，或在需要时处理添加依赖项。这已经在第7章介绍过了，这里就不再赘述了。注意，Doxygen是用CMake构建的，所以也可以使用源代码生成。
+为用户生成文档，或在需要时处理添加依赖项。这已经在第7章介绍过了，这里就不再赘述了。Doxygen是用CMake构建的，也可以使用源码生成。
 
-在系统中安装Doxygen和Graphviz后，可以将生成添加到项目中。与网上消息来源所暗示的不同，这并不像我们想象的那么困难或复杂。不需要创建外部配置文件，提供到doxygen可执行文件的路径，或添加自定义目标。从CMake 3.9开始，可以使用FindDoxygen查找模块中的doxygen\_add\_docs()函数，设置文档目标。
+在系统中安装Doxygen和Graphviz后，可以将生成添加到项目中。与网上消息来源不同，这并不像我们想象的那么困难或复杂。不需要创建外部配置文件，提供到doxygen可执行文件的路径，或添加自定义目标。从CMake 3.9开始，可以使用FindDoxygen查找模块中的doxygen\_add\_docs()函数，设置文档目标。
 
 其签名是这样的:
 
@@ -49,15 +49,15 @@
 	[COMMENT comment])
 \end{lstlisting}
 
-第一个参数指定目标名称，需要用-t参数显式地构建cmake(在生成构建树之后)，如下所示:
+第一个参数指定目标名称，需要用-t参数显式地构建cmake(在生成构建树之后):
 
 \begin{tcblisting}{commandshell={}}
 cmake --build <build-tree> -t targetName
 \end{tcblisting}
 
-或者，可以通过添加ALL参数来构建它(通常没有必要)。其他选项都是不言自明的，除了USE\_STAMP\_FILE。这允许CMake在没有任何源文件更改的情况下跳过文档的重新生成(但要求sourceFilesOrDirs只包含文件)。
+或者，可以通过添加ALL参数来构建(通常没有必要)。其他选项都是不言自明的，除了USE\_STAMP\_FILE。这允许CMake在没有任何源文件更改的情况下跳过文档的重新生成(但要求sourceFilesOrDirs只包含文件)。
 
-我们将遵循前几章的实践，创建一个带有辅助函数的实用程序模块(可以在其他项目中重用)，如下所示:
+我们将遵循前几章的实践，创建一个带有辅助函数的程序模块(可以在其他项目中重用):
 
 \begin{lstlisting}[style=styleCMake]
 # chapter-10/01-doxygen/cmake/Doxygen.cmake
@@ -80,14 +80,14 @@
 endfunction()
 \end{lstlisting}
 
-该函数接受两个参数——输入和输出目录——并将创建一个自定义doxygen目标。事情是这样的:
+该函数接受两个参数——输入和输出目录——并将创建一个自定义doxygen目标:
 
 \begin{enumerate}
 \item 
 首先，使用CMake的内置Doxygen查找模块来确定系统中是否有Doxygen可用。
 
 \item 
-若不可用，将创建一个虚拟doxygen目标，将通知用户并运行一个错误命令，该命令(在类Unix系统上)返回1，导致构建失败。这时用return()结束函数。
+若不可用，将创建一个伪doxygen目标，通知用户并运行一个错误命令，该命令(在类Unix系统上)返回1，导致构建失败。这时用return()结束函数。
 
 \item 
 若Doxygen可用，将在提供的输出目录中生成HTML。Doxygen是可配置的(在官方文档中找到更多信息)，要设置任何选项，只需按照示例调用set()并在其名称前加上DOXYGEN\_。
@@ -96,9 +96,9 @@
 设置实际的doxygen目标:所有DOXYGEN\_变量将转发到doxygen的配置文件中，文档将从源树中提供的输入目录生成。
 \end{enumerate}
 
-若文档是由用户生成的，那么步骤2可能需要安装必要的依赖项。
+若文档是由用户生成的，步骤2可能需要安装必要的依赖项。
 
-要使用这个函数，可以将它添加到项目的主列表文件中:
+要使用这个函数，可以将其添加到项目的主列表文件中:
 
 \begin{lstlisting}[style=styleCMake]
 # chapter-10/01-doxygen/CMakeLists.txt
@@ -120,7 +120,7 @@
 图10.1 Doxygen生成的类引用
 \end{center}
 
-成员函数文档中可以看到，描述通过在头文件中用适当的注释在方法前面添加:
+成员函数文档中可以看到，通过在头文件中用适当的注释在方法前面添加:
 
 \begin{lstlisting}[style=styleCXX]
 // chapter-10/01-doxygen/src/calc.h (fragment)
@@ -136,14 +136,14 @@
 
 这种格式称为Javadoc。打开带有双星号的注释块很重要:/**。更多信息可以在Doxygen的文档块描述中找到(参见扩展阅读部分的链接)。
 
-若安装了Graphviz，Doxygen将检测它并生成依赖关系图，如下所示:
+若安装了Graphviz，Doxygen将检测它并生成依赖关系图:
 
 \begin{center}
 \includegraphics[width=0.8\textwidth]{content/3/chapter10/images/2.jpg}\\
 图10.2 Doxygen生成的继承和协作图
 \end{center}
 
-通过直接从源代码生成文档，创建了一种机制，可以使用整个开发周期中发生的更改快速更新文档。此外，注释中任何的遗漏都有可能在代码审查期间发现。
+通过直接从源代码生成文档，创建了一种机制，可以使用整个开发周期中发生的更改快速更新文档。此外，注释中的遗漏都有可能在代码审查期间发现。
 
 许多开发者会抱怨Doxygen提供的设计过时了，这让他们在向客户展示生成的文档时犹豫不决。别担心，这个问题很容易解决。
 

content/3/chapter10/3.tex

@@ -1,8 +1,8 @@
 
 
-用干净、新颖的设计编写项目文档也很重要。毕竟，若把所有的工作都投入到为前沿项目编写高质量的文档中，那么必须让用户这样看待它。Doxygen拥有所有花哨的功能，但并不以紧跟最新的视觉趋势而闻名。然而，这并不意味着我们需要付出很多努力来改变这一点。
+用干净、新颖的设计编写项目文档也很重要，若把所有的工作都投入到为前沿项目编写高质量的文档中，那么必须让用户这样看到它。Doxygen拥有所有花哨的功能，但并不以紧跟最新的视觉时尚趋势而闻名。然而，这并不意味着需要付出很多努力才能改变这一点。
 
-幸运的是，一个名为jothepro的开发人员创建了一个名为doxygen-awesome-css的主题，提供了一个现代的、可定制的设计。它甚至有一个黑暗模式!可以在下面的截图中看到:
+一个名为jothepro的开发人员创建了一个名为doxygen-awesome-css的主题，提供了一个现代的、可定制的设计，甚至有一个黑暗模式!可以在下面的截图中看到:
 
 \begin{center}
 \includegraphics[width=0.8\textwidth]{content/3/chapter10/images/3.jpg}\\
@@ -12,10 +12,10 @@
 该主题不需要任何额外的依赖项，可以很容易地从其GitHub页面(\url{https://github.com/jothepro/doxygen-awesome-css})获取。
 
 \begin{tcolorbox}[colback=blue!5!white,colframe=blue!75!black,title=Note]
-在线教程建议使用多个应用程序串行执行来升级体验。一种流行的方法是使用Breathe和Exhale扩展将Doxygen的输出转换为Sphinx。这个过程看起来有点麻烦，会引入许多其他依赖项(比如Python)。我建议尽可能保持工具的简单性，很有可能不是项目中的每个开发人员都能很好地理解CMake，如此复杂的过程会给他们带来困难。
+在线教程建议使用多个应用程序串行执行来升级体验，流行的方法是使用Breathe和Exhale扩展将Doxygen的输出转换为Sphinx。这个过程看起来有点麻烦，会引入许多其他依赖项(比如Python)。我建议尽可能保持工具的简单性，很有可能不是项目中的每个开发人员都能很好地理解CMake，如此复杂的过程会给他们带来麻烦。
 \end{tcolorbox}
 
-将直接进入这个主题的自动采用，看看看如何扩展我们的Doxygen.cmake，通过添加一个新的宏来使用它:
+将这个主题的自动采用，来看看如何扩展我们的Doxygen.cmake，通过添加一个新的宏来使用它:
 
 \begin{lstlisting}[style=styleCMake]
 # chapter-10/02-doxygen-nice/cmake/Doxygen.cmake (fragment)
@@ -45,13 +45,13 @@
 将doxy-awesome-css使用Git下载下来，并通过FetchContent模块提供给项目。
 
 \item 
-按照主题的README文件的建议，配置了Doxygen的额外选项。
+按照主题的README文件的建议，配置了Doxygen的选项。
 
 \item 
 DOXYGEN\_HTML\_EXTRA\_STYLESHEET配置主题的.css文件的路径，其将复制到输出目录。
 \end{itemize}
 
-可以想象，最好在Doxygen函数中调用这个宏，就在doxygen\_add\_docs()之前，像这样:
+最好在Doxygen函数中调用这个宏，就在doxygen\_add\_docs()之前:
 
 \begin{lstlisting}[style=styleCMake]
 # chapter-10/02-doxygen-nice/cmake/Doxygen.cmake
@@ -69,7 +69,7 @@
 
 宏中的所有变量都在调用函数的作用域中设置。
 
-现在可以在生成的HTML文档中享受现代风格，并自信地与世界分享它。
+现在可以在生成的HTML文档中享受现代风格，并自信地与世界进行分享。
 
 
 

content/3/chapter10/4.tex

@@ -1,9 +1,9 @@
 
-这一简短的章节中，我们介绍了如何将文档生成工具Doxygen添加到CMake项目中，并使其变得优雅。这个过程不太复杂，将极大地改善解决方案中的信息流。花在添加文档上的时间将是一项值得的开销，特别是当发现您或您的团队成员在理解应用程序中的复杂关系方面有困难时。
+这一简短的章节中，我们介绍了如何将文档生成工具Doxygen添加到CMake项目中，并使其变得优雅。这个过程不太复杂，将极大地改善解决方案中的信息流。花在添加文档上的时间将是一项值得的开销，特别是当发现您或您的团队成员在理解应用中的复杂关系方面有困难时。
 
 可能会担心将Doxygen添加到一个从一开始就不使用文档生成的大型项目中会很困难，向每个函数添加注释所需的大量工作可能会让开发人员不堪重负。不要追求立即完成:从小处着手，只填写最近提交中接触到的元素的描述。即使是大部分不完整的文档也比完全没有文档要好。
 
-记住，通过生成文档，将强制它接近实际代码:若它们都在同一个文件中，那么维护书面解释与逻辑同步就更容易了。另外，与大多数程序员一样，您可能是一个非常忙碌的人，最终会忘记项目的一些小细节。记住:好记性不如烂笔头。帮自己一个忙，先把事情写下来。
+通过生成文档，将强制它接近实际代码:若都在同一个文件中，那么维护书面解释与逻辑同步就更容易了。另外，与大多数程序员一样，您可能是一个非常忙碌的人，最终会忘记项目的一些小细节。记住:好记性不如烂笔头。帮自己一个忙，先把事情写下来。
 
 下一章中，我们将学习如何使用CMake自动化项目的打包和安装。
 

content/3/chapter10/5.tex

@@ -14,7 +14,7 @@
 
 \subsubsubsection{10.5.1\hspace{0.2cm}其他文档生成工具}
 
-还有许多其他的工具在本书中没有涉及到，因为我们关注的是CMake支持的项目。然而，其中一些可能更适合您。若喜欢探索，可以访问两个我觉得有趣的项目，将地址列在这里:
+因为我们关注的是CMake支持的项目，所以还有许多其他的工具在本书中没有涉及。然而，其中一些可能更适合您。若喜欢探索，可以访问两个我觉得有趣的项目，将地址列在这里:
 
 \begin{itemize}
 \item 

content/3/chapter11/0.tex

@@ -1,11 +1,11 @@
 
-我们的项目已经构建、测试和文档化，是时候向我们的用户发布它了。本章主要讨论我们为此需要采取的最后两个步骤:安装和打包。这些都是高级技术，建立在我们目前所学的基础之上:管理目标及其依赖关系、瞬时使用需求、生成器表达式等。
+我们的项目已经构建、测试和文档化，是时候向用户发布了。本章主要讨论为此需要采取的最后两个步骤:安装和打包。这些都是高级技术，建立在我们目前所学的基础之上:管理目标及其依赖关系、使用需求、生成器表达式等。
 
-安装允许项目在系统范围内发现和访问。本章中，将介绍如何导出目标，以便另一个项目可以在不安装的情况下使用，以及如何安装项目，以便系统上的任何程序都可以轻松使用。特别是，将学习如何配置我们的项目，以便够自动地将不同的工件类型放在正确的目录中。为了处理更高级的场景，我们将介绍用于安装文件和目录的低层命令，以及用于执行定制脚本和CMake命令的低层命令。
+安装允许项目在系统范围内发现和访问。本章中，将介绍如何导出目标，以便另一个项目可以在不安装的情况下使用，以及如何安装项目，以便系统上的程序都可以轻松使用，并学习如何配置项目，以便够自动地将不同的工件类型放在正确的目录中。为了处理更高级的场景，将介绍用于安装文件和目录的低层命令，以及用于执行定制脚本和CMake的低层指令。
 
 接下来，将学习如何设置可重用的CMake包，以便通过从其他项目调用find\_package()来发现它们，将解释如何确保目标及其定义不固定在文件系统上的特定位置。还将讨论如何编写基本和高级配置文件，以及与包相关的版本文件。
 
-然后，为了使事情模块化，将简要介绍组件的概念，包括CMake包和install()指令。所有这些准备工作都是为本章的最后一个方面做准备:使用CPack来生成归档文件、安装程序、打包文件和不同操作系统中所有包管理器都能识别的包。这些可用于携带预构建的工件、可执行文件和库。这是终端用户开始使用我们软件最简单的方式。
+然后，为了模块化，将简要介绍组件的概念，包括CMake包和install()指令。所有这些准备工作都是为本章的最后一个方面做准备:使用CPack来生成归档文件、安装程序、打包文件和不同操作系统中所有包管理器都能识别的包。这些可用于携带预构建的工件、可执行文件和库。这是终端用户使用软件最简单的方式。
 
 本章中，我们将讨论以下主题: