c++ - 使 Doxygen 读取双斜杠 C++ 注释作为标记

Question

我正在尝试设置自动化 Doxygen在我们庞大的 78,000 个文件 C++ 代码库上运行。提取基本类型和层次结构信息没问题，但我想让它更智能地提取已经存在的文档注释。

多年来积累的大多数评论确实遵循一般模式，尽管不是 Doxygen 预期的模式。大多数情况下它们看起来像

// class description
class foo
{
   // returns ascii art of a fruit
   const char* apples( void ); 

   // does something to some other thing
   customtype_t baz( foo &other );

   enum
   {
      kBADGER, // an omnivorous mustelid
      kMUSHROOM, // tasty on pizza
      kSNAKE,  // oh no!
   };
}

双斜杠，而不是 ///或 //! Doxygen 所期望的样式注释。

要搜索和替换所有这些注释的文件太多了，而且我的许多程序员对在他们的代码中看到三斜杠非常过敏，所以我想找到一些方法让 Doxygen 读取普通注释作为 JavaDoc 注释，当它们位于正确的位置时。 有没有办法让 Doxygen 读取 //作为 /// ?

我找不到任何这样的配置参数，所以我想我需要以某种方式转换输入。一般来说，我会使用的规则是:

• 如果有一行只包含一个评论，紧接在前面函数/类/类型/变量声明，假设它是 ///评论。
• 如果有声明在同一行后面跟着 //评论，将其视为 ///<

但我不知道如何教 Doxygen 这条规则。我能想到的两种方式是:

1. 将程序编写为 INPUT_FILTER ，它解析输入 C++ 并转换 //转入 /// s 同上。但是这种转换对于正则表达式来说太复杂了，我真的不想写一个完整的 C++ 解析器只是为了将输入提供给另一个 C++ 解析器!此外，为每个文件启动一个 INPUT_FILTER 程序会降低 Doxygen 的速度，这是无法接受的:运行我们的源代码已经需要 30 多分钟，并且添加了 INPUT_FILTER需要六个多小时。
2. 修改 Doxygen 源代码以包含上述注释规则。在不熟悉的代码中，这似乎是一项可怕的工作。

还有其他想法吗？

Answer 1

答案很简单:你不能。

必须使用 doxygen 的特殊样式，将注释标记为文档。

Doxygen 不仅接受声明之前的注释。您也可以在代码中的任何地方使用它们。

如果您想使用 doxygen 功能，则必须手动更新注释，或者编写一个脚本/工具来查找声明和前面的注释来更改它们。

您必须决定，从 3 个解决方案中选择一个(您的两个，以及脚本，作为答案添加)或不使用 doxygen。