Comment documenter les dépendances globales pour les fonctions?

Question

J'ai un code C d'un fournisseur tiers (pour une plate-forme intégrée) qui utilise des variables globales (pour la vitesse & optimisations d'espace). Je documente le code, en convertissant au format Doxygen.

Comment ajouter une note dans la documentation de fonction que la fonction requiert sur les variables globales et les fonctions?

Doxygen a des commandes spéciales pour l'annotation des paramètres et des valeurs de retour comme décrit ici: Doxygen Special Commands. Je n'ai vu aucune commande pour les variables globales.

Exemple de code C:

extern unsigned char data_buffer[]; //!< Global variable. 

    /*! Returns the next available data byte. 
    * \return Next data byte. 
    */ 
    unsigned char Get_Byte(void) 
    { 
     static unsigned int index = 0; 
     return data_buffer[index++]; //!< Uses global variable. 
    } 

Dans le code ci-dessus, je voudrais ajouter Doxygen commentaires que la fonction dépend de la variable globale data_buffer.

Answer 1

Vous pouvez simplement ajouter une note à cet effet et utiliser la directive \link pour diriger le lecteur vers la description de la variable globale.

Answer 2

Doxygen pourrait faire avec une commande @global pour compléter @param. Jusqu'à ce que ce jour arrive, vous pouvez l'approximer avec des alias.

Dans votre fichier de configuration Doxygen ajouter les alias suivants:

ALIASES += global_START="<dl class=\"params\"><dt>Globals</dt><dd><table class=\"params\">" 
ALIASES += global_{2}="<tr><td class=\"paramname\">\1</td><td>: \2</td></tr>" 
ALIASES += global_END="</table></dd></dl>" 

Exemple d'utilisation:

int fxnMAIN_Main(void) 
{ 
    /** 
    * @brief Bla Bla Bla. 
    * 
    * @global_START 
    * @global_{bExampleOne, Description Here} 
    * @global_{bExampleTwo, Second Description Here} 
    * @global_END 
    * 
    * @retval int : Bla Bla Bla. 
    */ 

    // Code Here 
}