Discussion :

[all-du-34]

Bonjour, je viens de découvrir doxygen, je trouve que c’est un très bon logiciel pour réaliser la documentation mais une chose me paraît complètement illogique, dans mon code source je dois d’abord écrire la description de la fonction, puis écrire son prototype.

Je trouve que cela donne un effet brouillon à mon ficher source…
Il y a-t-il moyen d’écrire les blocs de documentation après les prototypes ?

Merci d’avance pour votre réponse.

[koala01]

Salut,

Avant tout, il faut au contraire considérer qu'il est "logique" que la description de la fonction se trouve avant le prototype de celle-ci.

Le fait est que tu vas, sans doute comme tout le monde, lire ton fichier de la première ligne à la dernière.

En ayant la "documentation" d'une fonction avant de voir comment elle se présente, tu pourras donc "assez facilement" savoir si une fonction correspond à ce que tu recherches comme fonctionnalité, avant même d'avoir vu son nom ou son prototype, et, si ce n'est pas la fonction dont tu as besoin, tu pourras passer à la suivante sans t'inquiéter d'avantage

Ceci étant dit, il est tout à fait possible de "déporter" les commentaires destinés à doxygen "n'importe où": Tu pourrais très bien décider de placer l'ensemble de la documentation au tout début du fichier, à sa toute fin, ou même carrément décider de créer un fichier tout à fait à part qui ne contient que la documentation (une extension qui sera reconnue par doxygen dans ce cas est, par exemple un *.dox, mais tu peux également définir ta propre extension en cas de besoin )

La "seule chose", c'est qu'il te faudra alors avoir recours à des balises comme @class @fn et autres, et qu'il te faudra aussi veiller à fournir les noms "pleinement qualifiés".

Cependant, je ne te conseille vraiment pas de déporter la documentation de tes classes et fonction, je trouve, au contraire, particulièrement utile d'avoir cette description juste avant la classe ou la fonction décrite (car cela te permet, comme je te l'ai dit, de profiter de la documentation lorsque tu lis ton fichier d'en-tête ).

Enfin, il faut savoir qu'il est souvent utile de rajouter des pages "qui n'ont rien à voir" avec la seule documentation de ton code source comme:

• La création de groupes qui te permettent de regrouper "tout ce qui va bien ensemble"
• le fait de fournir des informations concernant certains concepts
• Le fait de présenter des considérations "philosophiques" qui expliquent la raison de certains choix de conceptions (ou que l'on veut voir respecter durant la conception)
• ...

Tout cela peut aisément être mis en place grâce à doxygen, et, comme ce n'est pas "à proprement parler" des informations relatives au code source, il semble intéressant de placer ce genre de documentation dans des fichiers "à part"

[drake84450]

Non tu ne peux pas. Si tu écris après, ce sera le prototype suivant qui va être commenté. A moins de tout commenter a part comme il est dit dans le message précédent.

[koala01]

Non tu ne peux pas. Si tu écris après, ce sera le prototype suivant qui va être commenté.

En fait, il y a moyen de le faire... mais, comme je l'ai dit, je ne recommande vraiment pas d'avoir recours à cette possibilité

[all-du-34]

Merci de vos réponses.
Vous m’avez convaincu, même si je trouve que cela donne un effet « brouillions » je vais donc continuer à noter la description avant les prototypes.

[koala01]

Merci de vos réponses.
Vous m’avez convaincu, même si je trouve que cela donne un effet « brouillions » je vais donc continuer à noter la description avant les prototypes.

Mais qu'est ce qui fait que tu trouves que ca donne un effet "brouillons"