使 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 期望的樣式注釋。

通過搜索和替換所有此類注釋，go 的文件太多了，而且我的許多程序員對在他們的代碼中看到三斜杠非常過敏，所以我想找到一些方法讓 Doxygen 將普通注釋讀取為 JavaDoc評論，當他們在正確的地方。 有沒有辦法讓 Doxygen 讀/// //

我找不到任何這樣的配置參數，所以我想我需要以某種方式轉換輸入。 一般來說，我使用的規則是：

• 如果在函數/類/類型/變量聲明之前有一行只包含注釋，則假定它是///注釋。
• 如果在同一行有一個聲明后跟//注釋，則將其視為///<

但我不知道如何教 Doxygen 這條規則。 我能想到的兩種方法是：

1. 編寫一個程序作為INPUT_FILTER ，它解析輸入 C++ 並將// s 轉換為/// s 如上所述。 但是這種轉換作為正則表達式太復雜了，我真的不想寫一個完整的 C++ 解析器只是為了將輸入提供給另一個 C++ 解析器，另外：為每個文件啟動一個 INPUT_FILTER 程序Doxygen 的運行速度令人無法接受，運行我們的源代碼已經需要 30 多分鍾，而添加INPUT_FILTER則需要 6 多小時。
2. 修改 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])