From 13db6d5af14038c2a8a02732f68f9b05cba50c56 Mon Sep 17 00:00:00 2001 From: toknow-gh Date: Sun, 24 Sep 2023 20:51:18 +0800 Subject: [PATCH] Translated tech/20220526 Document your source code with Doxygen on Linux.md --- ... your source code with Doxygen on Linux.md | 254 ----------------- ... your source code with Doxygen on Linux.md | 255 ++++++++++++++++++ 2 files changed, 255 insertions(+), 254 deletions(-) delete mode 100644 sources/tech/20220526 Document your source code with Doxygen on Linux.md create mode 100644 translated/tech/20220526 Document your source code with Doxygen on Linux.md diff --git a/sources/tech/20220526 Document your source code with Doxygen on Linux.md b/sources/tech/20220526 Document your source code with Doxygen on Linux.md deleted file mode 100644 index ca06fb74e1..0000000000 --- a/sources/tech/20220526 Document your source code with Doxygen on Linux.md +++ /dev/null @@ -1,254 +0,0 @@ -[#]: subject: "Document your source code with Doxygen on Linux" -[#]: via: "https://opensource.com/article/22/5/document-source-code-doxygen-linux" -[#]: author: "Stephan Avenwedde https://opensource.com/users/hansic99" -[#]: collector: "lkxed" -[#]: translator: "toknow-gh" -[#]: reviewer: " " -[#]: publisher: " " -[#]: url: " " - -Document your source code with Doxygen on Linux -====== -This widely used open source tool can generate documentation from your comments. - -![5 trends in open source documentation][1] - -Image by: Internet Archive Book Images. Modified by Opensource.com. CC BY-SA 4.0 - -When trying to familiarize yourself with someone else's project, you usually appreciate the comments left behind that help you understand the meaning of their code. In the same way, whenever you are programming, whether for yourself or for others, it is good practice to comment your own code. All programming languages offer a special syntax to mark a word, a line, or a whole section as a comment. Those areas are then ignored by the compiler or interpreter when the source code is processed. - -Comments don't take the place of documentation, but there is a way to use your comments to produce documentation easily. Meet [Doxygen][2], an open source tool for generating HTML or LaTeX documentation based on comments in the code. Doxygen enables you to provide a comprehensive overview of the structure of your code without additional effort. While Doxygen is mainly used to document C++, you can use it for many other languages, like C, Objective-C, C#, PHP, Java, Python, and more. - -To use Doxygen, you simply comment your source code in a syntax that Doxygen can read. Doxygen then walks through your source files and creates HTML or LaTeX documentation based on those special comments. The C++ example project below will illustrate how the source code is commented and how the documentation is generated from it. The example is available on [GitHub][3], and I will also include references to different sections of the [Doxygen manual and documentation][4]. - -### Install Doxygen on Linux - -On Fedora, Doxygen is available as a package. Open a terminal and run: - -``` -sudo dnf install doxygen -``` - -On Debian-based systems, you can install it by running: - -``` -sudo apt-get install doxygen -``` - -### Usage - -Once installed, all you need is a project with Doxygen-compatible comments and a Doxyfile, a configuration file that controls the behavior of Doxygen. - -Note: If you stick to the related example project on GitHub, you can omit the next step. - -If there is no `Doxyfile` yet, you can simply let Doxygen generate a standard template. To do so, navigate to the root of your project and run: - -``` -doxygen -g -``` - -The `-g` stands for generate. You should now notice a newly created file called `Doxyfile`. You can invoke Doxygen by simply running: - -``` -doxygen -``` - -You should now notice two newly created folders: - -* html/ -* latex/ - -By default, Doxygen outputs LaTeX-formatted documentation as well as HTML-based documentation. In this article, I will focus only on HTML-based documentation. You can find out more about LaTeX output in the official Doxygen documentation, in the *Getting started* section. - -Double click on `html/index.html` to open the actual HTML documentation. With a blank configuration, it probably looks like the screenshot below: - -![A screenshot of a doxygen generated main page on Firefox. The content field under My Project Documentation is blank.][6] - -Now it's time to modify the `Doxyfile` and add some special comments to the source code. - -### Doxyfile - -The `Doxyfile` allows you to define tons of adjustment possibilities, so I will describe only a very small subset. The settings correspond to the `Doxyfile` of the example project. - -#### Line 35: Project name - -Here you can specify the project name, which will be visible in the header line and the browser tab. - -``` -# The PROJECT_NAME tag is a single word (or a sequence of words surrounded by -# double-quotes, unless you are using Doxywizard) that should identify the -# project for which the documentation is generated. This name is used in the -# title of most generated pages and in a few other places. -# The default value is: My Project. - -PROJECT_NAME           = "My Project" -``` - -#### Line 47: Project brief description - -The brief description will also be shown in the header but in a smaller font. - -``` -# Using the PROJECT_BRIEF tag one can provide an optional one line description -# for a project that appears at the top of each page and should give viewer a -# quick idea about the purpose of the project. Keep the description short. - -PROJECT_BRIEF          = "An example of using Doxygen in C++" -``` - -#### Line 926: Inclusion of subdirectories - -Allow Doxygen to walk recursively through subdirectories to find source and documentation files. - -``` -# The RECURSIVE tag can be used to specify whether or not subdirectories should -# be searched for input files as well. -# The default value is: NO. - -RECURSIVE = YES -``` - -#### Line 1769: Disable LaTeX output - -If you are just interested in the HTML output, you can disable the LaTeX code generation using this switch. - -``` -# If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output. - -# The default value is: YES. - -GENERATE_LATEX = NO -``` - -After every change, you can run Doxygen again to check whether your changes have had the desired effect. If you just want to check which modification an existing `Doxyfile` has, invoke Doxygen with the `-x` switch: - -![A screenshot of the terminal showing the differences, Project Name, Project Brief, Recursive, and status of Generate Latex][7] - -As with the command `diff`, Doxygen displays only the differences between the actual Doxyfile and the template. - -### Special comments - -Doxygen reads the sources and checks each file for special comments. Based on those comments and keywords, it builds up the HTML documentation. The anatomy of the special comments can be well explained using the header file of the class ByteStream, as shown in the GitHub example linked above. - -I will look at the constructor and destructor as an example: - -``` -/*! @brief Constructor which takes an external buffer to operate on -* -* The specified buffer already exist. -* Memory and size can be accessed by buffer() and size(). -* -* @param[in] pBuf Pointer to existing buffer -* @param[in] size Size of the existing buffer -*/ - -ByteStream(char* pBuf, size_t size) noexcept; -``` - -There are different flavors of formatting a special comment block. I prefer to start the comment in the Qt-style (`/*!` ) and add an asterisk (`*` ) before each line. The block then ends with an asterisk followed by a forward slash (`*/` ). To get an overview of the different style options, refer to the Doxygen manual, in the section *Documenting the code*. - -Comments in Doxygen are divided into two sections, a brief description and a detailed description. Both sections are optional. In the code sample above, the comment block refers to the following line of code, the declaration of a constructor. The sentence behind the `@brief` will be shown in the compact class overview: - -![A screenshot of the C++ example of using Doxygen showing the Byte Stream Class Reference. The categories in the list are public member functions, writing (operators for writing to the stream), and reading (operators for reading from the stream)][8] - -After a blank line (blank lines are treated as paragraph separators), the actual documentation for the constructor begins. With the `@param[in/out]` keyword, you can mark the arguments passed to the constructor, and Doxygen will make a clear argument list from it: - -![Screenshot of the Doxygen example showing the parameters under ByteStream][9] - -Note that Doxygen automatically creates a link to the mentioned `buffer()` and `size()` method in the comment. In contrast, the comment before the destructor declaration won't have any effect on Doxygen as it is not recognized as a special comment: - -``` -// Destructor -~ByteStream(); -``` - -Now you have seen 90% of the magic. By using a slightly modified syntax for your comments, you can convert them into special comments that Doxygen can read. Furthermore, by using a few keywords, you can advance the formatting. In addition, Doxygen has some special features, which I will highlight in the following section. - -### Features - -Most of the work is already done via your regular commenting on the source code. But with a few tweaks, you can easily enhance the output of Doxygen. - -#### Markdown - -For advanced formatting, Doxygen supports Markdown syntax and HTML commands. There is a Markdown cheat sheet available in the [download section][10] of opensource.com. - -#### Mainpage - -Aside from your customized header, you will get a mostly empty page when you open `html/index.html`. You can add some meaningful content to this empty space by using specific keywords. Because the main page is usually not dedicated to a particular source code file, you can add an ordinary text file containing the content for the main page into the root of your project. You can see this in the example on GitHub. The comments in there produce the following output: - -![The Doxygen Example Documentation field now contains headings and documentation: Introduction, Running the example, System requirements, and Building the code, with step by step examples and code snippets (all can be found in the example on GitHub)][11] - -#### Automatic link generation - -As noted above, Doxygen automatically figures out when you are referring to an existing part of the code and creates a link to the related documentation. Be aware that automatic link creation only works if the part you refer to is documented as well. - -More information can be found in the official documentation, under *Automatic link generation*. - -#### Groups - -The ByteStream class has overloaded stream operators for writing (`<<` ) and reading (`>>` ). In the class overview in the **Special comments** section above, you can see that the operator declarations are grouped as Writing and Reading. These groups are defined and named in the ByteStream header file. - -Grouping is done using a special syntax: You start a group with `@{` and end it with `}@`. All members inside those marks belong to this group. In the header `ByteStream.h` it is implemented as follows: - -``` -/** @name Writing -* Operators for writing to the stream -* @{ -*/ - -(...) - -/** @} -* @name Reading -* Operators for reading from the stream -* @{ -*/ - -(...) - -/** @} */ -``` - -You can find more information about grouping in the Doxygen documentation, under *Grouping*. - -#### LLVM Support - -If you are building with [Clang][12], you can apply the flag `-Wdocumentation` to the build process to let Clang check your special comments. You can find more information about this feature in the LLVM Users Manual or in Dmitri Gribenko's presentation, both on the Clang website. - -### Where Doxygen is used - -Doxygen was first released in 1997, so it has been already around for some years. Despite its age, many projects use Doxygen to create their documentation. Some examples are NASA's [F Prime][13] flight software framework, the image processing library [OpenCV][14], and the package manager [RPM][15]. You can also find the Doxygen syntax in other areas, like in the documentation standards of the content management platform [Drupal][16]. - -A caveat: One drawback of using Doxygen is that it outputs HTML documentation with the look and feel of web pages from the nineties. It is also hard to depict the architecture of meta and template programming using Doxygen. For those cases, you would probably choose [Sphinx][17] over Doxygen. - --------------------------------------------------------------------------------- - -via: https://opensource.com/article/22/5/document-source-code-doxygen-linux - -作者：[Stephan Avenwedde][a] -选题：[lkxed][b] -译者：[译者ID](https://github.com/译者ID) -校对：[校对者ID](https://github.com/校对者ID) - -本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出 - -[a]: https://opensource.com/users/hansic99 -[b]: https://github.com/lkxed -[1]: https://opensource.com/sites/default/files/lead-images/documentation-type-keys-yearbook.png -[2]: https://www.doxygen.n/ -[3]: https://github.com/hANSIc99/DoxygenSample -[4]: https://www.doxygen.nl/manual/ -[5]: https://opensource.com/downloads/doxygen-cheat-sheet -[6]: https://opensource.com/sites/default/files/2022-05/main%20page%20doxy.png -[7]: https://opensource.com/sites/default/files/2022-05/doxygen%20class%20overview.png -[8]: https://opensource.com/sites/default/files/2022-05/actual%20doxy%20byte%20stream%20class.png -[9]: https://opensource.com/sites/default/files/2022-05/argument%20list%20from%20Doxygen.png -[10]: https://opensource.com/downloads/cheat-sheet-markdown -[11]: https://opensource.com/sites/default/files/2022-05/main%20page%20doxygen.png -[12]: https://clang.llvm.org/ -[13]: https://github.com/nasa/fprime -[14]: https://docs.opencv.org/4.5.5/index.html -[15]: https://github.com/rpm-software-management/rpm -[16]: https://www.drupal.org/docs/develop/standards/api-documentation-and-comment-standards -[17]: https://opensource.com/article/18/11/building-custom-workflows-sphinx -[18]: https://opensource.com/downloads/doxygen-cheat-sheet diff --git a/translated/tech/20220526 Document your source code with Doxygen on Linux.md b/translated/tech/20220526 Document your source code with Doxygen on Linux.md new file mode 100644 index 0000000000..0e2b79b74e --- /dev/null +++ b/translated/tech/20220526 Document your source code with Doxygen on Linux.md @@ -0,0 +1,255 @@ +[#]: subject: "Document your source code with Doxygen on Linux" +[#]: via: "https://opensource.com/article/22/5/document-source-code-doxygen-linux" +[#]: author: "Stephan Avenwedde https://opensource.com/users/hansic99" +[#]: collector: "lkxed" +[#]: translator: "toknow-gh" +[#]: reviewer: " " +[#]: publisher: " " +[#]: url: " " + +在 Linux 上用 Doxygen 生成源代码文档 +====== +Doxygen 是一款广泛使用的开源文档生成工具，它通过代码注释来生成文档。 + +![5 trends in open source documentation][1] + +Image by: Internet Archive Book Images. Modified by Opensource.com. CC BY-SA 4.0 + +在试着熟悉别人的代码时，你总希望他们留下的代码注释能对你理解代码有所帮助。同理，无论为了自己还是其他人，编写代码时写注释是好习惯。所有编程语言都有专门的注释语法，注释可以是一个单词、一行文字、甚至是一整段话。编译器或解释器处理源代码时会忽略注释。 + +注释不能完全取代文档，但是有方法可以使用注释来生成文档。[Doxygen][2] 是一个开源的文档生成工具，它能够根据代码注释生成 HTML 或 LaTeX 格式的文档。Doxygen 让你在不用额外操作的情况下创建代码结构概览。尽管 Doxygen 主要是用来给 C++ 生成文档的，它对其它语言同样适用，比如 C、Objective-C、 C#、 PHP、Java 和 Python 等。 + +要使用 Doxygen，你只需要在源代码中使用 Doxygen 能够识别的语法来写注释。Doxygen 会扫描源码文件，然后根据这些特殊注释生成 HTML 或 LaTeX 文档。下面的示例项目会演示如何使用 Doxygen 注释，以及文档是如通过注释生成出来的。示例代码可从 [GitHub][3] 上获得，本文中也将引用 [Doxygen 手册及文档][4] 的相关章节。 + +### 在 Linux 上安装 Doxygen + +在 Fedora 上可以通过软件包的形式安装 Doxygen。打开终端运行命令： + +``` +sudo dnf install doxygen +``` + +在基于 Debian 的操作系统上，可以通过以下命令来安装： + +``` +sudo apt-get install doxygen +``` + +### 使用 + +安装完 Doxygen 后，你需要在项目中按 Doxygen 可以识别的格式来注释代码，还要提供一个 Doxyfile 配置文件来控制 Doxygen 的一些行为。 + +注意：如果你用的是 GitHub 上的示例项目，你可以忽略下面一步。 + +如果 Doxyfile 文件不存在，你可以用 Doxygen 生成一个标准 Doxyfile 模板文件。切换到项目根目录下，运行： + +``` +doxygen -g +``` +参数 `-g` 表示生成（generate）。现在应该会出现一个名为 `Doxyfile` 的新文件。通过命令调用 +Doxygen： + +``` +doxygen +``` + +现在应该能会有两个新文件夹： + +* html/ +* latex/ + +默认情况下，Doxygen 会同时输出 LaTeX 和 HTML 格式的文档。本文主要关注 HTML 文档。你可以在 Doxygen 官方文档的**入门**小节中找到关于 LaTeX 格式输出的更多信息。 + +双击 `html/index.html` 打开 HTML 文件。用空的配置文件生成的文档如下图： + +![A screenshot of a doxygen generated main page on Firefox. The content field under My Project Documentation is blank.][6] + +现在我们试着修改 `Doxyfile` 文件，并在源代码中添加特殊注释。 + +### Doxyfile 文件 + +在 `Doxyfile` 文件中可以定义大量的可调选项，本文通过介绍示例项目的 `Doxyfile` 文件我只能覆盖其中很小的子集。 + +#### 第 35 行：项目名称 + +你可以在这里指定项目名称，它最终会显示在页眉header和浏览器标签上。 + +``` +# The PROJECT_NAME tag is a single word (or a sequence of words surrounded by +# double-quotes, unless you are using Doxywizard) that should identify the +# project for which the documentation is generated. This name is used in the +# title of most generated pages and in a few other places. +# The default value is: My Project. + +PROJECT_NAME           = "My Project" +``` + +#### 第 47 行：项目简介 + +项目简介会以略小的字号显示在页眉上。 + +``` +# Using the PROJECT_BRIEF tag one can provide an optional one line description +# for a project that appears at the top of each page and should give viewer a +# quick idea about the purpose of the project. Keep the description short. + +PROJECT_BRIEF          = "An example of using Doxygen in C++" +``` + +#### 第 926 行：包含子目录 + +允许 Doxygen 查找源代码和文档文件时递归遍历子目录。 + +``` +# The RECURSIVE tag can be used to specify whether or not subdirectories should +# be searched for input files as well. +# The default value is: NO. + +RECURSIVE = YES +``` + +#### 第 1769 行：禁用 LaTeX 输出 + +如果你只想生成 HTML 文档，可以通过这个开关禁用 LaTeX 输出。 + +``` +# If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output. + +# The default value is: YES. + +GENERATE_LATEX = NO +``` +修改完成后，你可以再次运行 Doxygen 来检验修改是否生效了。可以在调用 Doxygen 时使用 `-x` 选项来查看 `Doxyfile` 文件的变更项： + +![A screenshot of the terminal showing the differences, Project Name, Project Brief, Recursive, and status of Generate Latex][7] + +通过调用 `diff` 命令，Doxygen 仅显示当前 Doxyfile 文件和模板文件的差异。 + +### 特殊注释 + +Doxygen 通过扫描源代码文件中的特殊注释和关键字来生成 HTML 文档。示例项目中的 ByteStream 类的头文件可以很好地解释特殊注释的用法。 + +下面用构造函数和析构函数作为示例： + +``` +/*! @brief Constructor which takes an external buffer to operate on +* +* The specified buffer already exist. +* Memory and size can be accessed by buffer() and size(). +* +* @param[in] pBuf Pointer to existing buffer +* @param[in] size Size of the existing buffer +*/ + +ByteStream(char* pBuf, size_t size) noexcept; +``` + +特殊注释块有不同的格式风格。我倾向于使用 `/*!` 开头（Qt 风格），每行前添加 `*`，以 `*/` 结束注释块。你可以参考 Doxygen 手册的*文档化代码*小节，以大致了解不同的风格选项。 + +Doxygen 注释分两个部分：简要描述和详细描述。它们都是可选的。在上面的例子中的注释块是对紧跟其后的构造函数声明的描述。在 `@brief` 之后的文本会显示在类概览小节中： + +![A screenshot of the C++ example of using Doxygen showing the Byte Stream Class Reference. The categories in the list are public member functions, writing (operators for writing to the stream), and reading (operators for reading from the stream)][8] + +在空行（空行是段落分隔符）之后是构造函数的实际文档。用 `@param[in/out]` 关键字标注传递给构造函数的参数，Doxygen 基于此生成参数列表： + +![Screenshot of the Doxygen example showing the parameters under ByteStream][9] + +值得注意的是 Doxygen 为 `buffer()` 和 `size()` 方法自动生成了链接。相反，Doxygen 忽略了析构函数前的注释，因为它并没有使用特殊注释： + +``` +// Destructor +~ByteStream(); +``` + +现在你已经看到 Doxygen 的绝大部分功能了。通过使用一种稍微改良的注释格式，让 Doxygen 能够识别它们。通过使用一些关键字，你甚至可以进一步控制格式化。在下一节中，我会进一步介绍 Doxygen 的其它特性。 + +### 其它特性 + +现在几乎所有的工作都可以通过对源代码注释的方式完成。通过一些微调，你可以轻松地优化 Doxygen 的输出。 + +#### Markdown 格式 + +为了进阶的格式化，Doxygen 支持 Markdown 和 HTML 命令。Markdown 速查表可以在 [这里][10] 下载到。 + +#### 项目主页 + +除了自定义页眉之外，`html/index.html` 几乎没有其它内容了。你可以通过使用关键字向其中添加一些有意义的内容。因为主页通常不是针对某个源代码文件的，你可以将要显示在主页的内容放到项目根目录下的一个单独文件中。示例项目中就是这样做的，其输出效果如下： + +![The Doxygen Example Documentation field now contains headings and documentation: Introduction, Running the example, System requirements, and Building the code, with step by step examples and code snippets (all can be found in the example on GitHub)][11] + +#### 自动链接生成 + +上面已将提到了，当你引用代码的其它部分时，Doxygen 会自动识别并生成相应链接。但要注意，这要求被引用部分也有文档才行。 + +更多信息可以在官方文档的*自动链接生成*中找到。 + +#### 分组 + +ByteStream 类重载overload 了的读写流操作符 （`<<` 和 `>>`）。在类的概览中可以发现操作符被分为读和写两组。分组是在 ByteStream 的头文件中定义的。 + +分组的语法以标记 `@{` 开始，以 `}@` 结束。在标记范围中的内容都属于这个分组。在 `ByteStream.h` 中的实现如下： + + +``` +/** @name Writing +* Operators for writing to the stream +* @{ +*/ + +(...) + +/** @} +* @name Reading +* Operators for reading from the stream +* @{ +*/ + +(...) + +/** @} */ +``` + +你可以在官方文档的*分组*中找到更多相关信息。 + +#### LLVM 支持 + +如果你用 [Clang][12] 构建项目的话，可以通过使用 `-Wdocumentation` 选项让 Clang 对特殊注释进行检查。想了解该特性的更多信息，可以参考 LLVM 用户手册和 Dmitri Gribenko 的展示报告，它们可以在 Clang 网站上找到。 + +### 谁在用 Doxygen + +Doxygen 是在 1997 年首次发布的。尽管有些年头了，现在仍然有很多项目在使用 Doxygen。比如 NASA 的飞行软件框架 [F Prime][13]、图像处理库 [OpenCV][14]、包管理器 [RPM][15]。你还可以在其它领域发现 Doxygen 语法标记的身影，比如内容管理平台 [Drupal][16] 的文档标准中。 + +注意：Doxygen 输出的 HTML 文档风格类似于九十年代网页。并且它也难以描绘元编程和模板编程架构。在这些情况下，你应该选择 [Sphinx][17] 而不是 Doxygen。 + + +-------------------------------------------------------------------------------- + +via: https://opensource.com/article/22/5/document-source-code-doxygen-linux + +作者：[Stephan Avenwedde][a] +选题：[lkxed][b] +译者：[toknow-gh](https://github.com/toknow-gh) +校对：[校对者ID](https://github.com/校对者ID) + +本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出 + +[a]: https://opensource.com/users/hansic99 +[b]: https://github.com/lkxed +[1]: https://opensource.com/sites/default/files/lead-images/documentation-type-keys-yearbook.png +[2]: https://www.doxygen.n/ +[3]: https://github.com/hANSIc99/DoxygenSample +[4]: https://www.doxygen.nl/manual/ +[5]: https://opensource.com/downloads/doxygen-cheat-sheet +[6]: https://opensource.com/sites/default/files/2022-05/main%20page%20doxy.png +[7]: https://opensource.com/sites/default/files/2022-05/doxygen%20class%20overview.png +[8]: https://opensource.com/sites/default/files/2022-05/actual%20doxy%20byte%20stream%20class.png +[9]: https://opensource.com/sites/default/files/2022-05/argument%20list%20from%20Doxygen.png +[10]: https://opensource.com/downloads/cheat-sheet-markdown +[11]: https://opensource.com/sites/default/files/2022-05/main%20page%20doxygen.png +[12]: https://clang.llvm.org/ +[13]: https://github.com/nasa/fprime +[14]: https://docs.opencv.org/4.5.5/index.html +[15]: https://github.com/rpm-software-management/rpm +[16]: https://www.drupal.org/docs/develop/standards/api-documentation-and-comment-standards +[17]: https://opensource.com/article/18/11/building-custom-workflows-sphinx +[18]: https://opensource.com/downloads/doxygen-cheat-sheet