作爲記錄我的C++代碼庫的一部分,我試圖得到完整的Doxygen覆蓋範圍 - 也就是說,我希望我的所有(數百個)頭文件都具有適合所有公共API的Doxygen註釋,這樣我就可以在代碼庫上運行Doxygen並且看不到任何「警告:沒有記錄」警告。是否有一種方法可以減少完全Doxygen覆蓋所需的多餘評論數量?
一般來說,這只是一個通過和記錄的東西,但我已經注意到,我一直重複輸入相同的文字爲每個類。例如,我有本質上講,這許多情況下:
/** The Foo class represents blah blah blah */
class Foo
{
public:
/** Default constructor */
Foo();
/** Copy constructor
* @param rhs the object to make this object a copy of.
*/
Foo(const Foo & rhs);
/** Destructor */
~Foo();
/** Equality operator.
* @param rhs the object to compare against.
* @returns true iff this object and (rhs) are equal.
*/
bool operator == (const Foo & rhs) const;
/** Inequality operator.
* @param rhs the object to compare against.
* @returns true iff this object and (rhs) are not equal.
*/
bool operator != (const Foo & rhs) const;
/** Assignment operator
* @param rhs the object we should copy our state from
* @returns a reference to *this
*/
Foo & operator = (const Foo & rhs);
[...]
}
這些意見(通常情況下)更多或更少的一模一樣的每一個類,因爲這些功能/經營者幾乎總是工作完全針對每個相同的方式類。事實上,讓操作員或複製構造函數以某種其他方式行事將是一個值得懷疑的設計模式,因爲C++程序員通常希望操作員對每個類都以相同的方式工作。
我的問題是,是否有一些技巧可以讓我告訴Doxygen爲這些事情自動生成合理的文檔(例如通過某種模板或宏),而無需一次又一次手動輸入此文本?這將大大減少我必須輸入和維護的文本數量,並且還可以通過允許我刪除「no duh」變體的註釋以便讀者更容易地查找註釋,從而使頭文件變得混亂提供真正的洞察力。
我正在寫一個相當大的類庫。我已經寫了一個簡短的腳本,爲我的大多數類使用通用設計模式發佈機器人生成的骨架代碼。包括Doxygen評論,以及我手動修復搜索/替換的幾個關鍵字。我也找不到更好的方法。 –
@JeremyFriesner:「*警告:blah沒有記錄*」您是否考慮關閉這些警告?特別是圍繞參數和返回類型;沒有理由記錄它們。 –
@NicolBolas對於其他(更有趣的)功能和方法,經常有理由記錄它們。如果我只能關閉某些類別的成員的警告,那會很有用,但我認爲我沒有那種控制力。 –