doxygen 是（事实上的）标准文档语法规范吗？ [关闭]

Question

我们都有记录代码的好习惯，对吧？

如今，代码内文档本身具有语法。它几乎就像一种编程语言。问题是：

• 存在哪些（多少）文档语法规范？
• 是否有标准的文档语法？
• 谁在定义这个标准？是否有官方委员会或机构（例如定义 C++ 标准的机构）？
• 或者“doxygen”已经成为事实上的标准？

很难不听说过 doxygen。在我参与的每个开源软件项目中都提到了它。然而，查看官方 doxygen 网站，doxygen 定义任何类型的规范远非显而易见！我得到的印象当我阅读“它可以帮助我的方式”时，doxygen 只是一个提取代码内文档并将其呈现在漂亮 HTML 页面中的软件。查看 doxygen 的首页，我什至认为 doxygen 可以使用任何文档语法在 3rd 方规范中定义，然后将其提取并输出为 HTML。

另外，有趣的是，doxygen 网站没有将 doxygen 这个词大写，好像它不是他们软件的品牌，而是一个普通名词（嗯，是吗？）

doxygen 到底是什么？

• 解析引擎？
• HTML 渲染引擎？
• 第三方软件可以使用库来呈现他们自己的文档？
• 文档语法（事实上）规范？
• 以上所有？

我对 doxygen 和其他代码解析器（如 ANTLR、boost-spirit、Ragel...）之间的关系感到特别困惑。

例如，doxygen 能做什么而 ANTLR 不能，而 ANTLR 能做什么 doxygen 不能？

另外，看看 Drupal 项目。他们有：

• 他们自己的API module 是“Doxygen 文档生成器规范子集的实现”。
• 他们自己的grammar parser module（添加到上面的列表中，以及 doxygen 本身、ANTLR 等）。
• 他们自己的API web site 运行上述两个模块，提供 Drupal 代码内“doxygen”文档。

因此，拿 C++ 类比，似乎“doxygen”这个词被重载了，在不同的上下文中意味着不同的东西。

在 Drupal 项目中，“doxygen”不是指软件，而只是文档语法的（标准？）规范，尽管正如我上面所说，doxygen 网站本身的首页并没有声称变成这样！

所以，我的离别问题是：

是否有任何其他文档语法规范？

Answer 1

存在哪些（多少）文档语法规范？

几乎每个中型软件开发组织似乎都有自己的。它们通常包含在“编码风格指南”的保护伞下。

是否有标准的文档语法？

据我所知，有一些标准得到了广泛的应用。这肯定不是一个完整的列表：

• JavaDoc
• C# XML 文档格式 (ECMA-334)
• QDoc（有时会被误认为是 Doxygen）
• RubyDoc
• Plain Old Documentation (POD)

谁在定义这个标准？

没有标准。

是否有官方委员会或机构（例如定义 C++ 标准的机构）？

并非如此，尽管 C# XML 文档格式由标准组织 ECMA 管理。

或者“doxygen”已经成为事实上的标准？

Doxygen 不是标准。它承认许多标准。见http://www.doxygen.nl/manual/features.html。

通常大多数人使用 doxygen 来生成他们编写的文档，同时松散地遵循 QDoc 标准或 JavaDoc 标准。通常当人们谈论“the” doxygen 标准时，他们通常指的是 QDoc 文档样式，以及 doxygen 扩展的一些任意使用。我的经验是，大多数使用 doxygen 的组织并没有真正严格地遵循任何特定的约定，仅仅是因为 doxygen 没有强制执行。

...doxygen 定义任何类型的规范远非显而易见！

不是。

doxygen 是一个简单的软件，用于提取代码内文档并将其呈现在漂亮的 HTML 页面中。

没错。它还支持 XML、Latex、RTF 和 UNIX“手册”页面输出。

查看 doxygen 的首页，我什至认为 doxygen 可以使用 3rd 方规范中定义的任何文档语法并将其提取并输出为 HTML。

没有，但很多。

另外，有趣的是，doxygen 网站没有大写 doxygen 这个词，好像它不是他们软件的品牌，而是一个普通名词（嗯，是吗？）

它不是商业产品，Dimitri 不太关心品牌。

doxygen 到底是什么？

文档生成工具。

我对 doxygen 与其他代码解析器（如 ANTLR、boost-spirit、Ragel）之间的关系感到特别困惑......

那些是解析库。

例如，doxygen 能做什么而 ANTLR 不能，而 ANTLR 能做什么 doxygen 不能？

像 ANTLR 这样的库用于构建软件，而 doxygen 是用于生成文档的专用工具。因此，虽然您可以使用 ANTLR 编写文档生成器，但您不想使用 doxygen 构建编译器（我不是说不能，因为您肯定可以，我见过奇怪的东西）。

还有其他文档语法规范吗？

上面已经回答了。

希望这会有所帮助。

Answer 2

没有标准。

Doxygen 样式几乎是标准的（gcc 模板库使用它）。

http://en.wikipedia.org/wiki/Comparison_of_documentation_generators

Answer 3

你是对的 - Doxygen 本身更像是一个文档提取应用程序，而不是一个“评论标准”。它支持许多不同的文档样式 - JavaDoc（用“@”引入命令）、Doxygen 变体（用“\”引入相同的命令）、文档 XML 以及允许的注释块格式的许多变体。它还可以使用 cmets 的格式来指示内容是什么（例如，简短的描述不需要这样标记，可以从文本的第一句或段落中获取等）

因此，它是高度可配置的，但允许几乎每个程序员都有自己的风格，这会导致从一个项目到另一个项目的非标准混乱，并且通常在单个项目中的不同 cmets 之间 - 即使它们是由单个项目编写的程序员！好的一面是，只要评论保持在基本样式内，Doxygen 就会为您正确提取文档并将它们全部格式化为一致的外部文档。不利的一面是，尽管许多程序员“使用 doxygen cmets”（听起来很标准化），但他们的注释格式通常完全不同。

至少可以帮助解决您自己的项目/团队/公司中这种风格差异的解决方案（用于 Visual Studio）是我编写的插件 AtomineerUtils。这有助于您创作和更新 Doxygen、JavaDoc 和 XML 文档格式 cmets - 它会自动生成文档以节省大量时间，并更新 cmets 以使其与代码更改保持同步。在此过程中，它可以重新格式化注释以实现非常一致和可读的样式（以标准格式对条目进行排序，在 cmets 和代码之间以及条目之间强制使用空行，在条目中自动换行等）。用户可以设置模板来精确控制所有这些工作的方式，因此很容易精确地实现您想要的样式，但要使其在您的所有项目中保持一致。当您有多个程序员在处理一段代码时，这会大大提高一致性。

如果您在 Visual Studio 中编写文档，我建议您使用 XML 文档格式。它不像 Doxygen/JavaDoc 样式那样具有人类可读性，但它被 IDE 用于在您键入代码时提供实时智能感知数据，并导出为任何应用程序都可以轻松处理的 XML 文件，从而为您提供更多灵活性。 Doxygen 可以从这种格式构建文档，因此您仍然可以将 Doxygen 工具与 XML 源 cmets 一起使用。

Answer 4

还有其他文档语法规范吗？

是的，当然。例如，有 JavaDoc（或者无论如何拼写）。和微软的 XML 东西（不管怎样叫它）。

不过，在开源 C++ 领域，doxygen 似乎几乎是事实上的标准。当我最初听说 doxygen 时（大约 10 年前），周围曾经有其他人，但似乎他们已经消失了。