Question

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

多年来积累的大多数评论都遵循一般模式，尽管不是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这条规则。我能想到的两种方式是：

将程序编写为INPUT_FILTER，解析输入C ++并将//转换为/// s，如上所述。但是这种转换太复杂了，不能作为正则表达式，我真的不想写一个完整的C ++解析器只是为了将输入提供给另一个C ++解析器！此外，为每个文件启动INPUT_FILTER程序会降低Doxygen的速度令人无法接受：在我们的源代码中运行已超过30分钟，添加INPUT_FILTER会花费超过六个小时。
修改Doxygen源代码以包含上述注释规则。在不熟悉的代码中，这似乎是一项可怕的工作量。

还有其他想法吗？

Answer 1

答案很简单：你做不到。

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

Doxygen不仅会在声明之前发表评论。您也可以在代码中的任何地方使用它们。

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

你必须决定，从3个解决方案中选择一个（你的两个，脚本，作为答案添加）或不使用doxygen。

Answer 2

您可以使用脚本将注释更改为Doxygen样式，这是一个简单的python脚本，只需尝试一下：


#!/usr/bin/env python

import os
import sys
import re

def main(input_file, output_file):
    fin = open(input_file, 'r')
    fout = open(output_file, 'w')
    pattern1 = '^\s*//\s.*'
    pattern2 = '^\s*\w.*\s//\s.*'
    for line in fin.readlines():
        if re.match(pattern1, line) != None:
            line = line.replace('//', '///', 1)
        if re.match(pattern2, line) != None:
            line = line.replace('//', '///<', 1)
        fout.write(line)
    fin.close()
    fout.close()

if __name__ == '__main__':
    if len(sys.argv) != 3:
        print 'usage: %s input output' % sys.argv[0]
        sys.exit(1)
    main(sys.argv[1], sys.argv[2])

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

2 个答案: