Doxygen C ++約定

Question

我正處於C ++項目的開始階段，我從一開始就一直在使用Doxygen。

我想知道你在項目中如何使用Doxygen，即我有幾個問題：

1.你在哪里提出你的Doxygen評論？ 標題或來源？

我認為他們應該去標題，因為這是我尋找如何使用方法的地方。 但是，我想省略原型中的實際參數名稱，所以我不能使用@param - 或者我可以嗎？ 你是如何解決這個問題的？

你記錄所有方法嗎？

到目前為止我只記錄公共方法，你是怎么做到的？ 您是否記錄了訪問者方法和公共變量？

你總是填寫@param和@return嗎？

我工作的地方（它是Javadoc，但它是同一個問題），我們有一個約定只填充實際需要的屬性，即如果簡短描述說“返回xys if ......”，我們省略@return。 如果參數名稱很明顯，我們省略它們。 我還不確定我是否喜歡這種方法，你是怎么做到的？ 到目前為止，我只填寫了簡介而沒有其他內容，但並非所有方法原型都足夠簡單。

你用哪種風格？

Doxygen中有幾種樣式：Javadoc（/ ** ... /），QT（/ ！... * /）等等。 純粹出於興趣：你使用哪一個？ 我要使用Javadoc風格的ATM，因為我已經習慣了。

Answer 1

1.你在哪里提出你的Doxygen評論？ 標題或來源？

我無法回答這個問題，因為我實際上目前還不記得我傾向於在標題與來源方面記錄的位置。

你記錄所有方法嗎？

幾乎完全是的。 每個方法都會獲得某種形式的文檔， 除非從變量/方法名稱（以及方法的參數名稱）中可以立即看出它在具體內容中的作用。 我傾向於遵循“如果你不能通過它的名稱和參數名稱來解決方法的目的，它需要一個注釋。如果在評論之后你仍然無法解決方法的目的，重寫如果你仍然無法很快看到方法的目的，或者評論是“太長”（“太長”是一個任意的測量> _>），那么你需要重新編寫方法或者分開了。“

你總是填寫@param和@return嗎？

是。 即使從閱讀@brief非常明顯，或者@return是@brief中句子的精確副本，我仍然@brief它們填入。對於方法的文檔來說，擁有那種掃描屬性非常有用。 “哦，方法X，我知道它的作用和原因，但它在X情況下的返回值究竟是什么呢？” *檢查@return *。

你用哪種風格？

Javadoc自己，雖然這是完全主觀的。 我使用Javadoc語法，因為我花了一些時間用Java編寫並且習慣了這種語法。 我個人認為它比其他人更有意義 - 我根本不喜歡QT語法。

Answer 2

1.你在哪里提出你的Doxygen評論？ 標題或來源？

文檔位於標題中，因為這是定義接口的位置。

你記錄所有方法嗎？

對於類，我記錄了所有公共和受保護的方法，我通常只保留私有方法。

你總是填寫@param和@return嗎？

我更喜歡內聯參數文檔

/*!
 * \brief My great class.
 */
class Foo
{
public:
    /*!
     * \brief My great method.
     */
    void method(
        int parameter    //!< [in] parameter does something great
    );
};

使用\\param因為它會導致參數名重復，並且當懶惰的開發人員忘記更改doxygen時，很容易與代碼失去同步。

當返回void類型時， \\return被省略。 當方法可以拋出時，我總是使用\\throw throw。

你用哪種風格？

只要它在整個項目中一致無所謂。