Doxygenation de header - Page 1

yop,


Je suis en train de doxygener un programme pour apprendre à faire les choses bien. Mais je pense que l'effort en vaut la peine !

Je sèche un peu pour documenter un header :
Structures -> \struct + commentaire linéaire pour chaque membre
Enumération -> \enum + commentaire linéaire pour chaque valeur

Par contre, pour des lignes de ce genre, je ne sais pas quoi faire :

#define par_ArchiveFile     par__0000
#define par_ExtractFile     par__0001

unsigned short  par_ArchiveFile    (const char* Archive, const char* File, unsigned long Flags);
unsigned short  par_ExtractFile    (const char* Archive, const char* File, unsigned long Flags, const char* Folder);

Les fonctions sont déjà documentées dans le source, mais Doxygen est balaise, et il fait correspondre la déclaration de la fonction avec son implémentation, et donc retrouve les commentaires

Par contre, un bloc de define, je ne trouve rien. Comment les commenter ? Juste un commentaire linéraire pour chaque #define ? Par moyen d'avoir un bloc spécifique pour une telle suite de define ?

Je ne trouve pas ça très pratique de mettre la doc dans l’implémentation. Je suggère donc de la déplacer dans les .h. Enfin, si Doxygen le fait pour toi, ce n’est pas si grave, sauf quand quelqu’un voudra utiliser ton .h sans avoir la doc à disposition

Pour les defines je doute qu’on puisse les regrouper comme tu voudrais le faire. Mais en même temps est-ce que c’est bien utile de documenter ces defines qui n’ont qu’un rôle de wiring code, dont l’utilisateur ignorera tout simplement l’existence…

Bien vu pour l'emplacement de la documentation, je vais modifier ça.

Pour les defines, c'est pour que l'utilisateur qui inclut mon header sache à quoi correspondent ces define. Mais bon, en général, même si on les comprends pas, on vire pas les defines d'un fichier.

Pour les define, sont-ils utilisés par l'utilisateur ? Sinon, pourquoi ne pas faire un .h privé ?

Oui, ils le sont, j'ai un .h privé ailleurs.

Les define servent pour que le linker sache qu'il s'agit de liens dynamiques à donner à manger au kernel (un lib__0012 est équivalent à notre lib@0012 avec A68k).
La seule chose que l'utilisateur utilisera (sisi !), ce sont les lib_MaFonction, (équivalent de nos lib::MaFonction).

+1 sur le fait de mettre la doc des fonctions dans le header. En effet, si les utilisateurs ont le header ouvert / facilement accessible dans l'éditeur de code, il peut être suffisant pour certaines vérifs rapides de lire les commentaires contenus dans le .h, sans être obligés de regarder la doc générée par Doxygen.
(les headers d'ExtGraph sont maintenant faits comme ça, Doxygen a remplacé une doc faite auparavant à la main)

Comment faire la doc d'un format de fichier pour que ça ressorte dans Doxygen ?

Genre je voudrais presque voir apparaitre le bloc de commentaires brut que je vais taper pour commenter ce format, mais je ne sais pas comment le dire à Dox...

hmm idée -> une structure anonyme, sans champs définis, juste un typedef ? C'est pas génial mais bon
Vous avez mieux ?

Voilà, c'est ça que je veux documenter :

Un bloc verbatim ( http://www.stack.nl/~dimitri/doxygen/commands.html#cmdverbatim ) ?

Ah merci, c'est exactement ça !

Tiens d'ailleurs, j'avais ça, dans cet ordre :
- un bloc \file
- un bloc \verbatim
- deux blocs \fn

Etrangement, il me fourrait le bloc verbatim dans la description détaillée de la première fonction.
J'ai donc inclu le bloc \verbatim dans le bloc \file en gardant les balises. Il apparait donc dans la description détaillée du fichier. Ca marche aussi.

Lionel Debroux (./6) :
+1 sur le fait de mettre la doc des fonctions dans le header. En effet, si les utilisateurs ont le header ouvert / facilement accessible dans l'éditeur de code, il peut être suffisant pour certaines vérifs rapides de lire les commentaires contenus dans le .h, sans être obligés de regarder la doc générée par Doxygen.

Vrai, mais un inconvénient des commentaires dans les .h, c'est qu'il y a davantage de risque d'oublier de les mettre à jour quand tu modifies le code (et c'est plus casse-pieds à faire que quand ils sont juste à côté du code).

0²

Un bon gros cartouche au dessus d'une fonction, il n'y a que ça de vrai.

C'est vrai aussi

Et le header tu le documentes comment ? Tu fais un script pour t'extraire la doc et te créer le tarball release c'est ça ?

Perso j'y mets pas de commentaire, celui qui est intéressé peut soit lire la doc, soit directement les .c ^^

et comme nous au boulot on fait du closed source très très cher et très très propriétaire, on livre le fichier H rapidement documenté, et un fichier dll. du coup on a pas le choix, on documente dans le header et beaucoup plus brièvement dans la source. et puis une VRAI spec d'API qui contient tous les détails, pas autogénérée du tout