Utilisation correcte de Doxygen

Question

J'ai essayé de documenter mon projet C++ en utilisant Doxygen, avec peu de succès: Doxygen échoue à reconnaître certaines macros, et par conséquent des fonctions entières sont mal interprétées et la plupart du temps ne génèrent pas de docs . Exemple:

/** 
* \def  __MYLIB_FUNCTION_ATTRIBUTE(...) 
* \brief Some brief comment 
* \details Detailed doc 
* \sa  Some valid references 
*/ 
#define __MYLIB_FUNCTION_ATTRIBUTE(...) __attribute__(__VA_ARGS__) 

/** 
* \def  IN 
* \brief Tag for input arguments to a function 
* \details Blah... 
* \sa  OUT 
*/ 
#define IN 

/** 
* \def  OUT 
* \brief Tag for output arguments to a function 
* \details Blah... 
* \sa  IN 
*/ 
#define OUT 

class MyClass { 
public: 

    /** 
    * \fn  MyClass() 
    * \brief  Constructor for MyClass 
    * \details Hi! 
    */ 
    __MYLIB_FUNCTION_ATTRIBUTE(__always_inline__) 
    MyClass() { 
    } 

    /** 
    * \fn  const char *doNothing(const char *s IN) 
    * \brief  A weird function 
    * \details Some very weird doc 
    * \param[in] s No good parameter 
    */ 
    const char* __SXC_FUNCTION_ATTRIBUTE(__const__) doNothing(const char *s IN) { 
     return s; 
    } 
}; 

Documentation générée pour la classe ci-dessus est toujours manquant une description pour doNothing et IN est interprété en fonction! Est-ce que je fais quelque chose de mal ici?

Answer 1

Deux choses:

1) L'analyseur Doxygen ne "voit" le "IN" dans DoNothing (car il est retiré dans la phase de pré-traitement), de sorte que le \ fn ne devrait pas l'inclure: const char* doNothing(const char* s). BTW, ce \ fn n'est pas nécessaire: Doxygen associe automatiquement le commentaire s'il est immédiatement avant l'entité documentée.

2) Je ne sais pas dans quoi __SXC_FUNCTION_ATTRIBUTE se développe mais, si c'est quelque chose de similaire à __MYLIB_FUNCTION_ATTRIBUTE, cela risque de désorienter Doxygen. Pour contourner ce problème, vous pouvez soit définir ces macros à rien dans la section PREDEFINED du fichier de configuration de Doxygen, ou les définir certaines conditions dans les sources, comme ceci:

#ifdef DOXYGEN 
// Doxygen does not grok the normal definition of this 
#define __MYLIB_FUNCTION_ATTRIBUTE(...) 
#else 
#define __MYLIB_FUNCTION_ATTRIBUTE(...) __attribute__(__VA_ARGS__) 
#endif 

et mettre PREDEFINED = doxygen dans votre fichier de configuration.