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 ><