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

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的阅读//作为///？

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

• 如果有一行只包含注释,紧接在函数/类/类型/变量声明之前,则假定它是/// 注释.
• 如果// 评论在同一行后面有声明,则将其视为a///<

但我不知道怎么去教Doxygen这条规则.我能想到的两种方式是:

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

还有其他想法吗？

Answer 1

您可以使用脚本将注释更改为 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])