Соглашения Doxygen C ++

Question

Я нахожусь в начале проекта C ++ и с самого начала использую Doxygen.

Я хотел бы знать, как вы используете Doxygen в своем проекте, то есть у меня есть несколько вопросов:

1.Где вы размещаете ваши комментарии Doxygen?Заголовок или источники?

Я думаю, что они должны идти в заголовок, потому что именно там я ищу, чтобы узнать, как использовать методы.Однако я предпочитаю опускать реальные имена параметров в прототипах, поэтому я не могу использовать @param - или я могу?Как вы справляетесь с этим?

2.Документируете ли вы все методы?

Пока я документирую только публичные методы, как вы это делаете?Документируете ли вы методы доступа и публичные переменные?

3.Всегда ли вы заполняете @param и @return?

Где я работаю (это Javadoc, но это одна и та же проблема), у нас есть соглашение для заполнения только фактически необходимых свойств, т.е. если краткие описанияговорит "возвращает xys, если ...", мы опускаем @return.Если имена параметров очевидны, мы их опускаем.Я до сих пор не уверен, нравится ли мне такой подход, как ты это делаешь?Пока что я только заполнил краткое изложение и ничего больше, но не все прототипы методов достаточно просты для этого.

4.Какой стиль вы используете?

В Doxygen есть несколько стилей: Javadoc (/ ** ... /), QT (/ ! ... * /) иБольше.Чисто из интереса: какой из них вы используете?Я еду с банкоматом в стиле Javadoc, потому что я к этому привык.

Answer 1

1. Где вы размещаете ваши комментарии Doxygen? Заголовок или источники?

Я не могу ответить на этот вопрос, потому что на самом деле я не помню, где я склонен документировать с точки зрения заголовка и источника.

2. Вы документируете все методы?

Почти полностью да. Каждый отдельный метод получает документацию в той или иной форме, , если , то из имени переменной / метода (и имен параметров для методов) сразу видно, что он делает в специфике. Я склонен придерживаться правила: «Если вы не можете определить цель метода по его имени и именам параметров, ему нужен комментарий. Если после комментирования вы все еще не можете определить цель метода, перепишите комментарий. Если вы все еще не можете очень быстро увидеть цель метода или если комментарий «слишком длинный» (где «слишком длинный» - произвольное измерение> _>), вам необходимо переписать метод или разделить это. "

3. Вы всегда заполняете @param и @return?

Да. Даже если это ослепительно очевидно из чтения @brief, или если @return является точной копией предложения в @brief, я все равно заполняю их. Может быть очень полезно иметь такого рода свойство сканирования для методическая документация. «О, метод X, я знаю, что он делает и почему, но каково его возвращаемое значение в ситуации X снова?» * проверяет @return*.

4. Какой стиль вы используете?

Сам Javadoc, хотя это совершенно субъективно. Я использую синтаксис Javadoc, потому что некоторое время писал на Java и очень привык к этому синтаксису. Я также лично думаю, что это имеет больше смысла, чем другие - мне просто не нравится синтаксис QT.

Answer 2

1.Где вы размещаете ваши комментарии Doxygen?Заголовок или источники?

Документация идет в заголовках, поскольку здесь определен интерфейс.

2.Документируете ли вы все методы?

Для классов я документирую все открытые и защищенные методы, я обычно оставляю частные методы в покое.

3.Вы всегда заполняете @param и @return?

Я предпочитаю документацию по встроенным параметрам

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

использованию \param, так как это приводит к дублированиюимя параметра, и может легко выйти из синхронизации с кодом, когда ленивые разработчики забывают изменить doxygen.

\return опускается при пустом типе возврата.Я всегда использую \throw, когда метод может бросить.

4.Какой стиль вы используете?

Не имеет значения, если он соответствует всему проекту.