首页 文章

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

提问于
浏览 次
23

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

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

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

  • 是否有标准的文档语法？

  • 谁在定义这个标准？是否有正式的委员会或机构（就像有一个定义C标准的那样）？

  • 或"doxygen"成为事实上的标准？

很难不听说doxygen . 在我参与的每个开源软件项目中都提到过 . 但是，看看官方的doxygen网站， it is far from obvious that doxygen is defining any kind of specification! 当我读到"the ways it can help me"时，我得到的印象是doxygen只是一个提取代码内文档并提供的软件它在漂亮的HTML页面中 . 看看doxygen首页，我甚至认为doxygen可以使用第三方规范中定义的任何文档语法并将其解压缩并输出为HTML .

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

什么是doxygen真的吗？

  • 解析引擎？

  • 一个HTML呈现引擎？

  • 可以由第三方软件用来呈现自己的文档的库？

  • 文档语法（事实上）规范？

  • 以上所有？

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

例如，什么是doxygen可以做的，ANTLR不能，而ANTLR可以做氧吗？

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

  • 他们自己API module这是“Doxygen文档生成器规范子集的实现” .

  • 他们自己的grammar parser module（添加到上面的列表中，与doxygen本身一起，ANTLR等等） .

  • 他们自己API web site运行上述两个模块，提供Drupal in-code "doxygen"文档 .

因此，采用C类比，似乎“doxygen”这个词过载并且在不同的环境中意味着不同的东西 .

在Drupal项目中，“doxygen”并不是指软件，而是指文档语法的（标准？）规范，尽管如上所述，doxygen网站本身的头版并未声称是这样的事情！

所以，我的离题是：

Is there any other documentation syntax specification?

c++ documentation doxygen specifications documentation-generation

4 回答

  • 3

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

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

    是否有标准的文档语法？

    我所知道的一些标准有一些广泛使用 . 这肯定不是一个全面的清单：

    谁在定义这个标准？

    没有标准 .

    是否有正式的委员会或机构（就像有一个定义C标准的那个）？

    虽然C＃XML文档格式是由标准组织ECMA管理的，但事实并非如此 .

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

    Doxygen不是标准 . 它重新认识了许多标准 . 见http://www.stack.nl/~dimitri/doxygen/features.html .

    通常，大多数人使用Doxygen生成他们编写的文档，同时松散地遵循QDoc标准或JavaDoc标准 . 通常，当人们谈论“Doxygen”标准时，他们通常意味着QDoc文档样式，以及Doxygen扩展的任意使用 . 我的经验是，大多数使用Doxygen的组织并没有非常严格地遵循任何特定惯例，仅仅因为Doxygen没有强制执行 .

    ... doxygen定义任何规格都是显而易见的！

    事实并非如此 .

    doxygen只是一个提取代码内文档并将其呈现在漂亮的HTML页面中的软件 .

    对，就是这样 . 它还支持XML，Latex，RTF和UNIX“man”页面输出 .

    查看doxygen首页，我甚至认为doxygen可以使用第三方规范中定义的任何文档语法并将其解压缩并输出为HTML .

    不是，但很多 .

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

    它不是商业产品，Dimitri并不关心品牌 .

    什么是doxygen真的吗？

    文档生成工具 .

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

    那些是解析库 .

    例如，什么是doxygen可以做的，ANTLR不能，而ANTLR可以做氧不能？

    像ANTLR这样的库用于构建软件，而Doxygen是用于生成文档的专用工具 . 因此，虽然您可以使用ANTLR编写文档生成器，但您不希望使用Doxygen来构建编译器（我不说不能，因为当然可以，我已经看到了陌生的东西） .

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

    已在上面回答 .

    希望这可以帮助 .

    回复于
  • 31

    没有标准 .

    Doxygen风格几乎是标准的（gcc模板库使用它） .

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

    回复于
  • 7

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

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

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

    如果您在Visual Studio中进行文档编制，我建议使用XML文档格式 . 它不像Doxygen / JavaDoc样式那样具有人类可读性，但它被IDE用于在您键入时提供代码上的实时智能感知数据，并导出到任何应用程序可以轻松处理的XML文件，这为您提供了更多灵活性 . Doxygen可以使用这种格式构建文档，因此您也可以使用Doxygen工具和XML源注释 .

    回复于
  • 4

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

    当然是 . 例如，有JavaDoc（或者那是拼写的） . 和Microsoft的XML东西（不过那个叫做） .

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

    回复于

相关问题