Documenter les variables avec Doxygen dans C

Code:

#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");
}

Ce n'est pas de générer des descriptions pour iOne, iTwo et iThree bien que c'était mon intention. Comment puis-je résoudre ce problème?

OriginalL'auteur Pieter | 2010-01-14

  1. 8

    Vous devez ouvrir vos commentaires Doxygen commentaires avec /**.

    Il peut être plus clair pour ce faire, cependant:

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

    De cette façon, vous pouvez modifier le nom de la variable sans casser votre documentation et il est aussi plus facile sur d'autres programmeurs qui ont besoin de lire le code source, parce que la description de la variable est situé à côté de ça, pas quelque part d'autre dans le fichier.

    Merci pour les conseils. Vous avez raison au sujet de votre code fait plus de sens, mais je veux savoir comment faire les \var définition correctement à l'intérieur de mon code. Quelle serait la bonne façon de le faire?
    Pieter: tout d'Abord, je pense que vous avez besoin de documenter le fichier lui-même (/** @file */ ) et puis comme je l'ai dit dans ma réponse, je ne pense pas que Doxygen peuvent documenter les variables locales.
    Je ne pense pas que cela va fonctionner, car ils sont des variables locales. Vous devez améliorer cette réponse, pour l'instant ses trompeuses.

    OriginalL'auteur Nick Meyer

  2. 14

    DOxygen est faite du document de classes et de la fonction des en-têtes ou, en d'autres termes, la interface. Pensez à la documentation comme quelque chose que les autres programmeurs étude pour profiter de vos classes et de fonctions correctement. Vous ne devriez pas utiliser DOxygen à votre document de mise en œuvre. Au lieu de cela, le document vos variables locales de la source avec // ou /* */.

    Il y a un certain nombre de façons pour vous de faire des commentaires DOxygen, dont quelques exemples (pour les variables) peut être vu dans le manuel ici. J'ai copié ci-dessous.

    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
    Je trouve ça un peu confus que vous devez d'abord expliquer Doxygen ne doit pas être utilisé pour cela, mais de montrer ensuite le plein soutien de Doxygen donne pour la documentation. Avez-vous une source de que les états Doxygen était censé document "l'interface", mais pas le reste?
    L'extrait de code que j'fournir montre comment les variables de document qui sont membres de "fichier, struct, union, de classe, ou enum". Depuis des OP iOne, iTwo, iThree variables internes main() ils ne sont pas accessibles à n'importe quelle interface au niveau de la portée et, par conséquent, ne sera pas documenté par Doxygen. Mettre une autre manière: Doxygen ne l'est pas, et ne devrait pas, de générer de la documentation expliquant ce que la variable i dans la déclaration for(int i=0;i<10;i++) parce que le champ d'application de i est trop limitée pour que de faire sens.
    Je comprends maintenant. Merci!

    OriginalL'auteur Richard