制作Doxygen阅读双斜杠C++评论作为标记

我试图设置自动化Doxygen运行在我们庞大的78,000文件C++代码库上。提取基本类型和层次结构信息并没有问题，但我希望能够更加明智地提取已经存在的文档注释。制作Doxygen阅读双斜杠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的这条规则。两种方式我能想到的是：

写程序作为INPUT_FILTER，其分析输入C++和如上述变换// s转换///秒。但是这种转换对于正则表达式来说太复杂了，我真的不想编写一个完整的C++解析器来将输入提供给另一个C++解析器！另外，为每个文件启动一个INPUT_FILTER程序会让Doxygen变得不可接受：它已经超过30分钟才能运行我们的源代码，并且添加一个INPUT_FILTER会花费六个多小时。
修改Doxygen源代码以包含上述评论规则。这似乎是在陌生的代码中可怕的工作量。

还有其他想法吗？

来源

2011-06-28 Crashworks

如何在一次运行目录的小脚本中寻找代码中的'//'（带空格）并将其转换为'///'？另外，如果你的编码器对'///'过敏，告诉他们从药房拿到东西。 – Xeo

您可以修改doxygen的解析器，以便在某些地方使用“//”替代“///”。毕竟，Doxygen是开源的。从常见问题解答：'这可能不难调整src/scanner.l – rve

@Xeo如果我实际签出，修改和检查78000文件只是为了将评论修改为无人喜欢的格式，我会在午餐前被解雇。 – Crashworks

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

来源

2011-06-28 02:34:31

这也将修改不会立即在声明之前的注释 - 它会改变每个注释，无处不在。这会产生大量的错误输入。INPUT_FILTER为每个输入文件启动一个新的Python实例的方式也使得doxygen运行速度太慢（构建需要12小时，而不是30分钟） – Crashworks

两点：1.您可以使用正则表达式来跳过不立即声明之前的注释，上面的脚本只是一个简单的注释; 2.在项目的每个构建之前，不需要更改评论样式，只需执行一次，而不需要下一次做。 –

但是，如何编写与任何声明相匹配的正则表达式？这就是阻止我从尝试之前：我可以猜测如何编写匹配已知基本类型的简单声明的正则表达式，例如'int foo（char bar，bool baz）'，但不是当每个类型本身可能是一个复杂的typedef从其他地方的头文件引入，例如'ResultVar_t foo（CBadger＆a，CPizza b，..）' – Crashworks

答案很简单：你不能。

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

Doxygen不仅仅在声明之前进行评论。你也可以在代码中的任何地方使用它们。

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

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

来源

2011-06-28 19:02:10

制作Doxygen阅读双斜杠C++评论作为标记

回答

相关问题