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

Making Doxygen read double-slash C++ comments as markup

本文关键字：注释 C++ Doxygen 读取      更新时间：2023-10-16

我正试图在我们庞大的78000文件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这个规则。我能想到的两种方法是：

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

还有其他想法吗？

答案很简单：你做不到。

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

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

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

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

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