[Résolu] Utilisation de doxygen dans le code C++ • Forum • Zeste de Savoir

Dedeun, dimanche 05 avril 2020 à 10h35

Bonjour,

Je l’avoue: Documenter le code, je fais ça à la fin (s’il reste du temps!). Mais à partir de maintenant, c’est décidé, j’écris les commentaires en même temps que le code ! Il y aura un avant et un après ce post!

Mais avant de commencer, je viens vers vous pour avoir votre expérience, pour ne pas me perdre et commencer par des truc qui ne servent pas.

Pour le C++, je pense que l’outil à prendre, c’est Doxygen: c’est pratiquement un standard (Qui aurait un autre avis ?)

J’ai passé un peu de temps sur internet, mais j’ai eu toutes les réponses que j’attendais. Aussi, voici lune première liste de question :

Mettez-vous des balises Doxygen dans les .hpp, ou dans les .cpp, ou dans les deux ?
Est-il utile de mettre un tag \fn, ou Doxygen est-il capable de récupérer le nom des fonctions tout seul ? (de même pour les \class et les \struct)
Dans une fonction, décrivez vous les précondition/post condition ?
Dans une fonction, décrivez-vous les exceptions qui pourrez être levées ? Est si oui, comment vous faite pour celles induites par le code appelé ?
Y-a-t-il une différence entre \warning et \remarks ?
Y-a-t-il une différence entre \throws et \exception ?

Je commence, aussi j’aurai sûrement plein de question sur l’utilisation de l’outil d’extraction ! Mais ça viendra [peut être/sûrement] plus tard.

Merci d’avoir lu mon post, merci aussi si vous prenez un peu de temps pour y répondre.

Cordialement

05/04/20 à 10h35

+0 -0

lmghs, dimanche 05 avril 2020 à 13h26

Mettez-vous des balises Doxygen dans les .hpp, ou dans les .cpp, ou dans les deux ?

fonction: déclaration
classes: définitions

Donc, principalement dans les .h(pp), mais il peut y en avoir dans certains trucs @internal des .cpp

Est-il utile de mettre un tag \fn, ou Doxygen est-il capable de récupérer le nom des fonctions tout seul ? (de même pour les \class et les \struct)

Non. Jamais. Je trouve ça débile. Mais certains projets l’obligent. Je trouve le résultat particulièrement inesthétique — d’autant que mon Vim met une couleur différente pour mes tags et zones de cartouches doxygen (le screencast démontre autre chose, mais on peut voir le traitement des cartouches doxygen côté couleurs).

Dans le genre, je n’aime pas @brief et utilise systématiquement l’option java_autobrief. Du coup, il ne faut pas oublier le point à la fin ou de sauter une ligne.

Dans une fonction, décrivez vous les précondition/post condition ?

Oui, c’est très important.

Dans une fonction, décrivez-vous les exceptions qui pourrez être levées ? Est si oui, comment vous faite pour celles induites par le code appelé ?

Surtout les exceptions directes car il est difficile de les oublier. Les exceptions indirectes quand j’y pense/y fais attention/en ai conscience.

Je ne mets plus rien pour les bad_alloc aujourd’hui.

Je mets @throw None pour les fonctions noexcept.

Y-a-t-il une différence entre \warning et \remarks ?

Aucune idée. Essaie. @remarks n’est pas du même niveau que @note?

Y-a-t-il une différence entre \throws et \exception ?

Aucune.

Je rajouterai:

Par expérience, j’ai pu noter que sur un gros projet, ne pas mettre les groupes génère une doc inexploitable.
Pour les paramètres je rajoute [in], [out] et [in,out] — mais il me manque encore le [sink] pour les paramètres pris par rvref.
Je ne mets rien entre le nom du paramètre et sa doc — font ça ceux qui n’ont pas de couleur dans leur IDE ou qui ne regardent pas la doc générée
Il faut générer la doc et contrôler le résultat pour bien progresser avec doxygen
Pour @return ce qui vient derrière est une explication, pas le type!

05/04/20 à 13h26

Blog|Vimeries

+2 -0

Dedeun, dimanche 05 avril 2020 à 14h28
Modifié

Merci LMGHS,

Je viens de me rendre compte que tu as déjà fait pratiquement la même réponse sur OC, J’avais mal cherché! Excuse moi de t’avoir fait te répéter.

Je connais pas JAVA_AUTOBRIEF (normal, je connais rien !), je me renseigne.

En ce qui concerne les post-conditions et les invariants, j’ai un peu de mal à les mettre dans mon code … alors delà à les documenter !

Que veux-tu dire: "@remarks n’est pas du même niveau que @note?"

Edit: Il semble que ce soit la même commande, même effet sur la sortie. FinEdit.

Euh, c’est quoi les groupes ? C’est pas la même chose que les namespace ?

Pour les paramètres, quel avantage tu as à ajouter in, out, in,out ? Est ce que tu indiques quand ton paramètre est passé par argument ou en référence ? Est ce que tu indique s’il est passer en const ? (c’est pour ça que tu indiques "in", pour dire que c’est un const ?)

En tout cas, merci pour cette réponse, et comme tu me le proposes, je me fais un projet à 3 sous et j’essaye ! Je revendais sûrement …

Cordialement.

05/04/20 à 14h28
Modifié

+0 -0

lmghs, dimanche 05 avril 2020 à 15h18

L’auto brief permet d’éviter à devoir écrire le lourdingue @brief. Les docs sont déjà assez lourdes.

Quand on te dit "remarquez", "notez", ou "faites attention", tu ressens les choses comment? Ben, utilise les cartouches en conséquence.

Les groupes sont un artefact de doxygen pour forcer des morceaux à être documentés ensemble alors que sinon ils sont éparpillées et tous mis à plat. Dans un gros projet, on ne va pas forcément mettre des espaces de noms dans tous les sens pour tout regrouper. Genre on n’a pas std::containers::, std::algorithms::, std::maths::, etc. Ce serait vite lourd. Du coup, toutes les docs seraient ensemble. Les groupes permettent de rajouter une organisation.

Pour les paramètres cela indique si la fonction consomme, positionne, ou consomme et altère les paramètres réels. On retrouve ça dans IDL (COM et CORBA), Ada, etc. Exemple