製作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++評論作爲標記

回答

相關問題