En utilisant Doxygen avec C, commentez-vous la fonction prototype ou la définition? Ou les deux?

pour le document public APIs I à la déclaration, car c'est là que l'utilisateur regarde habituellement en premier si elle n'utilise pas la sortie doxygen.

Je n'ai jamais eu de problèmes avec la seule documentation sur un seul endroit, mais je l'ai utilisé avec C++; pourrait être différent avec C, bien que j'en doute.

ne l'écrivez jamais deux fois. Jamais. La documentation in-Source suit sec, aussi, particulièrement en ce qui concerne de telles perversions de copie-pâte.[/modifier]

Cependant, vous pouvez spécifier si vous voulez des avertissements pour les éléments non documentés . Bien que de telles mises en garde semblent bonnes en théorie, mon expérience est qu'elles sont rapidement plus un fardeau qu'une aide. La documentation de toutes les fonctions n'est généralement pas la solution (il y a une telle chose est la documentation redondante, ou même entravant la documentation, et surtout trop de documentation); une bonne documentation nécessite une personne bien informée passant du temps avec elle. Étant donné que, ces avertissements sont inutiles.

et si vous n'avez pas les ressources pour écrire une bonne documentation (Argent, Temps, peu importe...), que ces avertissements n'aideront pas non plus.

Cité de ma réponse à cette question: C / C++ Header file documentation :

j'ai mis de la documentation pour l'interface (Paramètres, valeur de retour, quoi le fonction does) dans le fichier d'interface (.h), et la documentation pour l' mise en œuvre ( comment la fonction n') dans le fichier d'implémentation (.C, .rpc .m.) J'écris un aperçu de la la classe tout simplement avant sa déclaration, de sorte le lecteur dispose d'une base immédiate information.

avec Doxygen, cela signifie que la documentation décrivant la vue d'ensemble, les paramètres et les valeurs de retour ( \brief , \param , \return ) sont utilisés pour documenter le prototype de fonction et la documentation en ligne ( \details ) est utilisé pour documenter le corps de fonction (vous pouvez également vous référer à ma réponse à cette question: comment être en mesure d'extraire des commentaires de l'intérieur d'un fonction dans doxygen? )

j'utilise souvent Doxygen avec C ciblant les systèmes embarqués. J'essaie d'écrire de la documentation pour n'importe quel objet en un seul endroit seulement, parce que la duplication va entraîner la confusion plus tard. Doxygen fait une certaine quantité de fusion des docs, donc en principe il est possible de documenter l'API publique dans le fichier .h , et d'avoir quelques notes sur la façon dont il fonctionne réellement saupoudré dans le fichier .c . J'ai essayé de ne pas le faire moi-même.

Si le fait de déplacer le document d'un endroit à l'autre modifie la quantité de mises en garde qu'il produit, cela peut être une indication qu'il peut y avoir quelque chose de subtilement différent entre la déclaration et la définition. Le code se compile-t-il avec-Wall-Wextra par exemple? Y a-t-il des macros qui mutent le code à un endroit et pas à l'autre? Bien sûr, Doxygen l'analyseur n'est pas un analyseur du langage, et il est possible de le confondre.

Nous commenter seulement les définitions de fonction, mais nous l'utilisons avec C++.

Écrire à deux endroits est de perdre du temps. Au sujet de l'avertissement, si votre documentation semble bon, peut-être que c'est une bonne façon d'ignorer ces avertissements.

je me suis posé la même question et j'ai été agréablement surpris de voir que Doxygen inclut réellement la même documentation en ligne qui est dans le .c fichier .h fichier lors de la navigation dans la documentation html générée. Par conséquent, vous ne devez pas répéter votre documentation en ligne, et Doxygen est assez intelligent pour l'inclure dans les deux endroits!

j'exécute la version Doxygen version 1.8.10.