Документирование переменных с помощью Doxygen в C

Question

Код:

#include <stdio.h>

/*
 * \var int iOne
 * \brief Integer 1
 */
/*
 * \var int iTwo
 * \brief Integer 2
 */
/*
 * \var int iThree
 * \brief Integer 3
 */

/**
 * \brief Imitates a sheep.
 */
void sheep();

/**
 * \brief Main function for test code
 */
int main() {
    int iOne, iTwo, iThree;
    iOne = 1;
    iTwo = 2;
    iThree = 3;
    printf("%d %d %d", iOne, iTwo, iThree);

    return 0;
}

void sheep() {
    printf("Meeeh");
}

Это не генерирует описания для iOne, iTwo и iThree, хотя это было моим намерением. Как мне это исправить?

Answer 1

DOxygen был создан для документирования классов и заголовков функций или, другими словами, интерфейса . Думайте о документации как о том, что другие программисты изучают, чтобы правильно использовать ваши классы и функции. Вы не должны использовать DOxygen для документирования вашей реализации. Вместо этого документируйте свои локальные переменные в источнике с помощью // или /* */.

Существует несколько способов комментировать в DOxygen, некоторые примеры которых (для переменных-членов) можно увидеть в руководстве здесь . Я скопировал их ниже.

int var; /*!< Detailed description after the member */

int var; /**< Detailed description after the member */

int var; //!< Detailed description after the member
         //!< 

int var; ///< Detailed description after the member
         ///< 

int var; //!< Brief description after the member

int var; ///< Brief description after the member

Answer 2

Вам нужно открыть свои комментарии как комментарии Doxygen с /**.

Может быть, это будет понятнее:

int main() {
   /** \brief Integer 1 */
   int iOne;
   /** \brief Integer 2 */
   int iTwo;
   /** \brief Integer 3 */
   int iThree;
   /** ... and so on ... */
}

Таким образом, вы можете изменить имя переменной, не нарушая вашу документацию, и это также облегчает работу других программистов, которым нужно читать ваш исходный код, потому что описание переменной находится рядом с ним, а не где-то еще в файле.