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 top

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 ?

2

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 smile

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…
avatar
« Quand le dernier arbre sera abattu, la dernière rivière empoisonnée, le dernier poisson capturé, alors vous découvrirez que l'argent ne se mange pas. »

3

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

4

Pour les define, sont-ils utilisés par l'utilisateur ? Sinon, pourquoi ne pas faire un .h privé ?
avatar
<<< Kernel Extremis©®™ >>> et Inventeur de la différence administratif/judiciaire ! (©Yoshi Noir)

<Vertyos> un poil plus mais elle suce bien quand même la mienne ^^
<Sabrina`> tinkiete flan c juste qu'ils sont jaloux que je te trouve aussi appétissant

5

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

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.
(les headers d'ExtGraph sont maintenant faits comme ça, Doxygen a remplacé une doc faite auparavant à la main)
avatar
Membre de la TI-Chess Team.
Co-mainteneur de GCC4TI (documentation en ligne de GCC4TI), TIEmu et TILP.
Co-admin de TI-Planet.

7

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 grin
Vous avez mieux ?

Voilà, c'est ça que je veux documenter :
doc
/**
 *  Archive format
 *
 *  short       Size of the file (AMS format)
 *  short       Number of files in the archive. May be 0
 *
 *  < file 1>
 *  char[18]    C-string filename. May contain a path
 *  short       File size (AMS format)
 *  ...         File data
 *
 *  even
 *
 *  < file 2>
 *  char[18]    C-string filename. May contain a path
 *  short       File size (AMS format)
 *  ...         File data
 *
 *  even
 *
 *  char[6]     Extension: 0,"para",0
 *  char        OTH_TAG
 */

8

avatar
Membre de la TI-Chess Team.
Co-mainteneur de GCC4TI (documentation en ligne de GCC4TI), TIEmu et TILP.
Co-admin de TI-Planet.

9

Ah merci, c'est exactement ça !

10

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.

11

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).
avatar
Zeroblog

« Tout homme porte sur l'épaule gauche un singe et, sur l'épaule droite, un perroquet. » — Jean Cocteau
« Moi je cherche plus de logique non plus. C'est surement pour cela que j'apprécie les Ataris, ils sont aussi logiques que moi ! » — GT Turbo

12

pencil

Un bon gros cartouche au dessus d'une fonction, il n'y a que ça de vrai.
avatar
Que cache le pays des Dieux ? - Forum Ghibli - Forum Littéraire

La fin d'un monde souillé est venue. L'oiseau blanc plane dans le ciel annonçant le début d'une longue ère de purification. Détachons-nous à jamais de notre vie dans ce monde de souffrance. Ô toi l'oiseau blanc, l'être vêtu de bleu, guide nous vers ce monde de pureté. - Sutra originel dork.

13

C'est vrai aussi smile
avatar
Membre de la TI-Chess Team.
Co-mainteneur de GCC4TI (documentation en ligne de GCC4TI), TIEmu et TILP.
Co-admin de TI-Planet.

14

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

15

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

« Tout homme porte sur l'épaule gauche un singe et, sur l'épaule droite, un perroquet. » — Jean Cocteau
« Moi je cherche plus de logique non plus. C'est surement pour cela que j'apprécie les Ataris, ils sont aussi logiques que moi ! » — GT Turbo

16

et comme nous au boulot on fait du closed source très très cher et très très propriétaire, grin 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 grin