开放文档格式（ODF）基于开放标准，你可以使用其它工具检查它们，甚至从中提取数据。你只需要知道从哪里开始。 过去，文字处理文件是封闭的专有格式。在一些较旧的文字处理软件中，文档文件本质上是该软件的内存转储。虽然这样可以让加载文件更快，但也使文档文件格式变得不透明。 2005 年左右，结构化信息标准促进组织Organization for the Advancement of Structured Information Standards（OASIS）为所有类型的办公文档定义了一种开放格式，即办公应用程序开放文档格式Open Document Format for Office Applications（ODF）。 由于 ODF 是基于 OpenOffice.org的 XML 文件规范的开放式标准，因此你也可以将其简称为 “开放文档格式”。 ODF 包括几种文件类型，包括用于 开放文档文本OpenDocument Text 文档的 ODT。 ODT 文件中有很多值得探索的内容，它的本质是一个 Zip 文件。 ODT 文件结构 跟所有 ODF 文件一样，ODT 文件实际上是一个 XML 文档和其它文件的 Zip 压缩包。 使用 Zip 可以占用更少的磁盘空间，同时也意味着可以用标准 Zip 工具来检查它。 我有一篇关于 IT 领导力的文章，名为“Nibbled to death by ducks”，我将其保存为 ODT 文件。 由于 ODF 文件是一个 zip 容器，你可以用 unzip命令来检查它： $ unzip -l 'Nibbled to death by ducks.odt' Archive: Nibbled to death by ducks.odt Length Date Time Name 39 07-15-2022 22:18 mimetype 12713 07-15-2022 22:18 Thumbnails/thumbnail.png 915001 07-15-2022 22:18 Pictures/10000201000004500000026DBF6636B0B9352031.png 10879 07-15-2022 22:18 content.xml 20048 07-15-2022 22:18 styles.xml 9576 07-15-2022 22:18 settings.xml 757 07-15-2022 22:18 meta.xml 260 07-15-2022 22:18 manifest.rdf 0 07-15-2022 22:18 Configurations2/accelerator/ 0 07-15-2022 22:18 Configurations2/toolpanel/ 0 07-15-2022 22:18 Configurations2/statusbar/ 0 07-15-2022 22:18 Configurations2/progressbar/ 0 07-15-2022 22:18 Configurations2/toolbar/ 0 07-15-2022 22:18 Configurations2/popupmenu/ 0 07-15-2022 22:18 Configurations2/floater/ 0 07-15-2022 22:18 Configurations2/menubar/ 1192 07-15-2022 22:18 META-INF/manifest.xml 970465 17 files 我想强调 Zip 文件结构的以下几个元素： mimetype文件用于定义 ODF 文档。处理 ODT 文件的程序，如文字处理程序，可以使用该文件来验证文档的 MIME 类型。对于 ODT 文件，它应该总是：application/vnd.oasis.opendocument.text META-INF目录中有一个manifest.xml文件。它包含查找 ODT 文件其它组件的所有信息。任何读取 ODT 文件的程序都从这个文件开始定位其它内容。例如，我的 ODT 文档的manifest.xml文件包含这一行，它定义了在哪里可以找到主要内容: content.xml文件包含文档的实际内容。 我的文档中只有一张截图，它位于 Pictures目录中。 从 ODT 中提取文件 由于 ODT 文档是一个具有特定结构的 Zip 文件，因此可以从中提取文件。 你可以先解压缩整个 ODT 文件，例如使用 unzip命令： $ unzip -q 'Nibbled to death by ducks.odt' -d Nibbled 一位同事最近向我要了一份我在文章中提到的图片。通过查看 META-INF/manifest.xml文件，我找到了嵌入图像的确切位置。用grep命令可以找到描述图像的行: $ cd Nibbled $ grep image META-INF/manifest.xml $ ls -F Configurations2/ manifest.rdf meta.xml Pictures/ styles.xml content.xml META-INF/ mimetype settings.xml Thumbnails/ 就是这张图片： 开放文档格式 ODF 是一种开放的文件格式，它可以描述文字处理文件（ODT）、电子表格文件（ODS）、演示文稿（ODP）和其它文件类型。 由于 ODF 格式基于开放标准，因此可以使用其他工具检查它们，甚至从中提取数据。 你只需要知道从哪里开始。所有 ODF 文件都以 META-INF/manifest.xml为“引导”文件，通过它你能找到其余的所有内容。 ...

在试着熟悉别人的代码时，你总希望他们留下的代码注释能对你理解代码有所帮助。同理，无论为了自己还是其他人，编写代码时写注释是好习惯。所有编程语言都有专门的注释语法，注释可以是一个单词、一行文字、甚至是一整段话。编译器或解释器处理源代码时会忽略注释。 注释不能完全取代文档，但是有方法可以使用注释来生成文档。Doxygen是一个开源的文档生成工具，它能够根据代码注释生成 HTML 或 LaTeX 格式的文档。Doxygen 让你在不用额外操作的情况下创建代码结构概览。尽管 Doxygen 主要是用来给 C++ 生成文档的，它对其它语言同样适用，比如 C、Objective-C、 C#、 PHP、Java 和 Python 等。 要使用 Doxygen，你只需要在源代码中使用 Doxygen 能够识别的语法来写注释。Doxygen 会扫描源码文件，然后根据这些特殊注释生成 HTML 或 LaTeX 文档。下面的示例项目会演示如何使用 Doxygen 注释，以及文档是如通过注释生成出来的。示例代码可从 GitHub上获得，本文中也将引用Doxygen 手册及文档的相关章节。 在 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 文件。用空的配置文件生成的文档如下图： 现在我们试着修改 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文件的变更项： 通过调用 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之后的文本会显示在类概览小节中： 在空行（空行是段落分隔符）之后是构造函数的实际文档。用 @param[in/out]关键字标注传递给构造函数的参数，Doxygen 基于此生成参数列表： 值得注意的是 Doxygen 为 buffer和size方法自动生成了链接。相反，Doxygen 忽略了析构函数前的注释，因为它并没有使用特殊注释： // Destructor ~ByteStream; 现在你已经看到 Doxygen 的绝大部分功能了。通过使用一种稍微改良的注释格式，让 Doxygen 能够识别它们。通过使用一些关键字，你甚至可以进一步控制格式化。在下一节中，我会进一步介绍 Doxygen 的其它特性。 其它特性 现在几乎所有的工作都可以通过对源代码注释的方式完成。通过一些微调，你可以轻松地优化 Doxygen 的输出。 Markdown 格式 为了进阶的格式化，Doxygen 支持 Markdown 和 HTML 命令。Markdown 速查表可以在 这里下载到。 项目主页 除了自定义页眉之外，html/index.html几乎没有其它内容了。你可以通过使用关键字向其中添加一些有意义的内容。因为主页通常不是针对某个源代码文件的，你可以将要显示在主页的内容放到项目根目录下的一个单独文件中。示例项目中就是这样做的，其输出效果如下： 自动链接生成 上面已将提到了，当你引用代码的其它部分时，Doxygen 会自动识别并生成相应链接。但要注意，这要求被引用部分也有文档才行。 更多信息可以在官方文档的自动链接生成中找到。 分组 ByteStream类重载overload 了的读写流操作符 （ 和 >>）。在类的概览中可以发现操作符被分为读和写两组。分组是在ByteStream的头文件中定义的。 分组的语法以标记 @{开始，以}@结束。在标记范围中的内容都属于这个分组。在ByteStream.h中的实现如下： /** @name Writing * Operators for writing to the stream * @{ */ (...) /** @} * @name Reading * Operators for reading from the stream * @{ */ (...) /** @} */ 你可以在官方文档的分组中找到更多相关信息。 LLVM 支持 如果你用 Clang构建项目的话，可以通过使用-Wdocumentation选项让 Clang 对特殊注释进行检查。想了解该特性的更多信息，可以参考 LLVM 用户手册和 Dmitri Gribenko 的展示报告，它们可以在 Clang 网站上找到。 谁在用 Doxygen Doxygen 是在 1997 年首次发布的。尽管有些年头了，现在仍然有很多项目在使用 Doxygen。比如 NASA 的飞行软件框架 F Prime、图像处理库OpenCV、包管理器RPM。你还可以在其它领域发现 Doxygen 语法标记的身影，比如内容管理平台Drupal的文档标准中。 注意：Doxygen 输出的 HTML 文档风格类似于九十年代网页。并且它也难以描绘元编程和模板编程架构。在这些情况下，你应该选择 Sphinx而不是 Doxygen。 ...