Discussion :

[jOJo73450]

Salut � tous,

J'ai commenc� � utilis� Doxygen pour documenter le code source d'une application en C++. J'arrive � faire de beaux diagrammes avec les appels de fonctions etc etc.

Question : j'aimerai documenter un peu plus les variables (private) de mes classes. J'aimerai pour �tre tr�s pr�cis que Doxygen g�n�re dans la documentation la liste des m�thodes appelants telle ou telle variable. Savez vous si c'est possible et si oui comment ? J'ai pas mal Googler mais je trouve rien. J'ai la derni�re version de Doxygen actuellement dispo.

Merci.

Jo�l

[koala01]

Salut,

Il "suffit" de faire pr�c�der tout ce que tu veux documenter de commentaires que doxygen pourra identifier comme lui �tant destin�s.

G�n�ralement, on utilisera les commentaires "multiligne" (/* ... */ ) avec la particularit� que l'on met deux �toiles au symbole de d�but (donc /** ... */ )

Ainsi, un code proche de

Code :

S�lectionner tout - Visualiser dans une fen�tre � part

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
/** a brief description for your class
  *
  * a more complicated description
  * 
  * each time you pass a line that just contains "*", you begin a new paragrah
  *
  */ 
class MyClass
{
    public:
        /** a usefull feature
          *
          * you can specify many interresting thinks like
          *
          * @param[in] param1 some usefull parameter
          * @param[in] param2 another usefull parameter
          * @return : a short desrciption for returned value
          * @pre a precondition to be respected
          * @post a post condition to be respected
          * @throw an exception thrown if something goes wrong
          * ...
          */
          Type foo(Type1 /* const & */ param1, Type2 /* const & */ param2) /* const */;
    private:
        /** a brief member description
          *
          * you may provide a longer description too
          *
          */
         Type member_;
};

sera reconnu par doxygen qui g�n�rera la documentation au correspondante pour foo et pour member_ (excuses moi si le texte est en anglais, mais c'est juste une habitude, et puis, ca �vite les accents qui ne pr�sentent pas tr�s bien quand ils sont r�cup�r�s par doxygen, du moins, avec ses r�glages par d�faut )

Il existe de tr�s nombreuses commandes reconnues comme telles par doxygen...

Tu en trouvera la description d�taill�e directement dans la documentation qui a normalement �t� install�e avec doxygen.

Typiquement, tu peux directement ouvrir le fichier html <chemin/vers>/doxygen/html/commands.html, qui les reprend toutes (auquel tu peut aussi acc�der directement en suivant le lien "special commands" sur la page d'introduction)

"hope it helps"

[jOJo73450]

Salut Koala,

Merci de ta r�ponse, mais je connais d�j� cela (j'ai lu la doc !)

Je parle bien ici d'une documentation automatique des variables permettant de connaitre quelles m�thodes/fonctions utilisent telle ou telle variable.

Je suis donc � la recherche d'un moyen pour g�n�rer cette documentation. peut �tre que Doxygen ne sais pas le faire aujourd'hui ? Peut �tre un autre outil pourrait le faire ?

A+
Jo�l

[mala92]

Doxygen est capable de te dire o� se trouve la variable que tu utilises dans une fonction, mais pas l'inverse.
Pour savoir o� est appel�e une variable, �a demande beaucoup plus d'analyse du code. Je doute qu'un g�n�rateur de doc ait cette fonctionnalit�.

[jOJo73450]

Salut Mala,

"Doxygen est capable de te dire o� se trouve la variable que tu utilises dans une fonction, mais pas l'inverse." --> Comment ? C'est exactement ce que je veux !

Ce que je cherche � faire est � mon avis du m�me niveau que la documentation des appels de fonctions.

Jo�l

[akirira]

Bonjour,

J'aimerai pour �tre tr�s pr�cis que Doxygen g�n�re dans la documentation la liste des m�thodes appelants telle ou telle variable.

Ta question est ambig�e: je ne sais pas ce que �a veut dire "appeller une variable". Moi, mon code appelle (� la rigueur) des fonctions, mais pas des variables

Si je comprend bien, soit un membre de classe 'foo', tu veux une liste des m�thodes de la classe qui utilisent cette variable.
Doxygen ne permet malheureusement pas de faire ceci. Pour ma part, la solution la plus bateau que j'utilise, c'est d'utiliser un nommage "intelligent" (i.e. bool _IsThisAndThat; au lieu de bool a; ) et de faire un b�te "rechercher" via mon IDE favorite.

[jOJo73450]

Salut Akirira,

Merci pour ta r�ponse. Oui effectivement, j'ai parl� un peu vite, on appelle pas des variables, on les utilise.

Je fais comme toi pour le nommage, avec un pr�fixe pour le type, par exemple UINT32 u32Index, CString sName, etc.

Jusqu'� pr�sent je fais des recherches avec l'IDE (Visual C++), mais c'est �videmment pas pratique � maintenir, surtout quand l'appli p�se quelques dizaines de milliers de ligne et qu'il y a des centaines de variables dans des dizaines de classes. Le tout dans un contexte multi-threading, raison initiale de ce besoin de documentation (mise en place de protection des ressources partag�es). Bref

Si quelqu'un connait un autre outils ....

Merci.
Jo�l

[JolyLoic]

Si je comprend bien, soit un membre de classe 'foo', tu veux une liste des m�thodes de la classe qui utilisent cette variable.
Doxygen ne permet malheureusement pas de faire ceci. Pour ma part, la solution la plus bateau que j'utilise, c'est d'utiliser un nommage "intelligent" (i.e. bool _IsThisAndThat; au lieu de bool a; ) et de faire un b�te "rechercher" via mon IDE favorite.

Attention aux utilisation non visibles, en particulier les constructeurs et le destructeur utilisent toutes els variables, sans pour autant qu'elle apparaissent forc�ment explicitement.

Et un autre cas, plus subtil encore, est tr�s g�nant en multithread est l'aliasing : On acc�de � une variable non pas directement, mais par l'interm�diaire d'un pointeur ou d'une r�f�rence que l'on a stock� pr�c�demment. Je ne suis pas certain que ce soit un probl�me soluble dans la totalit� des cas, m�me si une analyse de flux doit donner des informations int�ressantes.

[akirira]

Je ne suis pas certain que ce soit un probl�me soluble dans la totalit� des cas, m�me si une analyse de flux doit donner des informations int�ressantes.

Juste par curiosit�, qu'appelle tu une "analyse de flux" ? Du profilage de code ? Ou autre chose ?

[JolyLoic]

Je veux dire par l� un programme qui passe par tout le code source, regardant par o� on peut passer, et qui permettrait de savoir que dans le cas suivant :

Code :

S�lectionner tout - Visualiser dans une fen�tre � part

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
class A
{
  int myData;
};
 
void g(int *pi)
{
  ++(*pi); // Est-ce que c'est un accès aux données de A ?
}
 
int f1()
{
  int i;
  int *pi = &i;
  g(pi);
}
 
int f2()
{
  A a;
  g(&a.myData);
}

L'incr�mentation dans g est une modification de A, alors que si on supprime la fonction f2, elle ne l'est plus.

[Faelucc]

Bonjour,

Voici ce que j'ai compris de la question de base :

Si dans le code une fonction 'foo()' utilise un attribut 'attr_' (disons qu'il est prive), comment faire pour que dans la documentation il y ai marque :

Pour la fonction 'foo()' : "Utilise 'attr_'"
Pour l'attribut 'attr_' : "Utilise dans la fonction 'foo()'"

C'est "plus ou moins" possible (dans le sens "l'option existe, mais ca fonctionne pas bien").

Dans le fichier Doxyfile :

Code :

S�lectionner tout - Visualiser dans une fen�tre � part

1
2
3
4
5
6
7
8
9
10
11
# If the REFERENCED_BY_RELATION tag is set to YES
# then for each documented function all documented
# functions referencing it will be listed.
 
REFERENCED_BY_RELATION = YES
 
# If the REFERENCES_RELATION tag is set to YES
# then for each documented function all documented entities
# called/used by that function will be listed.
 
REFERENCES_RELATION    = YES

Avec ces deux options activees ainsi que 'EXTRACT_ALL' et 'EXTRACT_PRIVATE', ca devrait deja donner quelque chose.

Maintenant, ca risque de ne pas toujours tres bien fonctionner.
J'ai trouve vite fait ca :

Not all names in code fragments that are included in the documentation are replaced by links (for instance when using SOURCE_BROWSER = YES) and links to overloaded members may point to the wrong member. This also holds for the "Referenced by" list that is generated for each function.

For a part this is because the code parser isn't smart enough at the moment. I'll try to improve this in the future. But even with these improvements not everything can be properly linked to the corresponding documentation, because of possible ambiguities or lack of information about the context in which the code fragment is found.

(Source : http://www.stack.nl/~dimitri/doxygen/trouble.html)
En gros, a cause du parser ainsi que des ambiguites possibles, certain liens ne sont pas detectes.

Bon apres, j'ai peut etre pas du tout compris la question...

PS : desole pour les accents, j'en ai pas ><