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

Код:

#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, хотя это и было моим намерением. Как я могу это исправить?


c objective-c doxygen
person Pieter    schedule 14.01.2010    source источник

Ответы (2)


arrow_upward
8
arrow_downward

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

Хотя может быть понятнее сделать так:

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

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

person Nick Meyer    schedule 14.01.2010
comment
Спасибо за совет. Вы правы в том, что ваш код имеет больше смысла, но я хочу знать, как правильно сделать определение \var внутри моего кода. Как правильно это сделать? - person Pieter; 14.01.2010
comment
Питер: Прежде всего, я думаю, вам нужно задокументировать сам файл (/** @file */ ), а затем, как я сказал в своем ответе, я не думаю, что Doxygen может документировать локальные переменные. - person Joey; 14.01.2010
comment
Я не думаю, что это сработает, так как это локальные переменные. Вы должны улучшить этот ответ, так как на данный момент он вводит в заблуждение. - person DrBeco; 27.09.2014

arrow_upward
20
arrow_downward

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
person Richard    schedule 28.02.2013
comment
Меня немного сбивает с толку то, что вы сначала объясняете, что Doxygen не следует использовать для этого, а затем показываете полную поддержку, которую Doxygen оказывает для его документирования. У вас есть источник, в котором говорится, что Doxygen предназначен для документирования интерфейса, но не для всего остального? - person Zimano; 17.05.2017
comment
Фрагмент, который я предоставляю, показывает способы документирования переменных, которые являются членами файла, структуры, объединения, класса или перечисления. Поскольку переменные iOne, iTwo, iThree OP являются внутренними для main(), они недоступны ни в какой области уровня интерфейса и, следовательно, не будут документированы Doxygen. Иными словами, Doxygen не создает и не должен генерировать документацию, объясняющую, что делает переменная i в операторе for(int i=0;i<10;i++), потому что область действия i слишком ограничена, чтобы это имело смысл. - person Richard; 17.05.2017
comment
Теперь я понимаю. Спасибо! - person Zimano; 18.05.2017