Documentation du fichier d'en-tête C/C++

Question

Selon vous, quelle est la meilleure pratique lors de la création de fichiers d'en-tête publics en C++?

1. Les fichiers d'en-tête doivent-ils contenir une documentation non, brève ou massive? J'ai vu tout de presque aucune documentation (s'appuyant sur une documentation externe) à de grandes spécifications d'invariants, de paramètres valides, de valeurs de retour etc. Je ne suis pas sûr exactement de ce que je préfère, une grande documentation est agréable puisque vous avez toujours accès à D'un autre côté, un fichier d'en-tête avec une documentation très brève peut souvent montrer une interface complète sur une ou deux pages de texte, donnant un meilleur aperçu de ce qu'il est possible de faire avec une classe.

2. Disons que je vais avec quelque chose comme une documentation brève ou massive. Je veux quelque chose de similaire à javadoc où je documente les valeurs de retour, les paramètres, etc. Quelle est la meilleure convention pour cela en C++? Autant que je me souvienne, doxygen fait de bonnes choses avec la documentation de style doc de java, mais y a-t-il d'autres conventions et outils pour cela, je devrais être au courant avant de passer à la documentation de style javadoc?

Answer 1

Habituellement, je mis la documentation pour l'interface (paramètres, la valeur de retour, ce la fonction fait) dans le fichier d'interface (.h) et la documentation de la mise en œuvre (comment fait la fonction) dans la mise en œuvre fichier (.c, .cpp, .m).

J'écris un aperçu de la classe juste avant sa déclaration, afin que le lecteur dispose d'informations de base immédiates.

L'outil que j'utilise est Doxygen.

Answer 2

1. je serais definetely avoir une certaine documentation dans l'en-tête des fichiers eux-mêmes. Cela améliore grandement le débogage pour avoir les informations à côté du code, et non dans des documents séparés. En règle générale, je documente l'API (valeurs de retour, argument, changements d'état, etc.) à côté du code, et des aperçus architecturaux de haut niveau dans des documents séparés (pour donner une vue plus large de la façon dont tout est assemblé; difficile de placer cela ensemble avec le code, car il référence généralement plusieurs classes à la fois).

2. Doxygen est très bien d'après mon expérience.

Answer 3

Mettez suffisamment dans le code pour qu'il puisse être autonome. Presque tous les projets dans lesquels la documentation était séparée étaient périmés ou n'étaient pas terminés, en partie parce que, s'il s'agit d'un document distinct, il s'agit d'une tâche distincte, en partie parce que la direction ne l'a pas prévu. en budgétisation. Documenter en ligne dans le cadre du flux fonctionne beaucoup mieux dans mon expérience.

Ecrivez la documentation sous une forme reconnue par la plupart des éditeurs comme un bloc; pour C++ cela semble être/* plutôt que //. De cette façon, vous pouvez le plier et voir les déclarations.

Answer 4

Vous pourriez être intéressé par gtk-doc. Il peut être « un peu difficile à configurer et utiliser » mais vous pouvez obtenir une bonne documentation de l'API à partir du code source, qui ressemble à ceci:

String Utility Functions

Answer 5

Je crois Doxygen est la plate-forme la plus courante pour générer la documentation et pour autant que je sache, il est plus ou moins en mesure de couvrir JavaDoc-notation (ne se limite pas à bien sûr).J'ai utilisé doxygen pour C, avec des résultats OK, je pense que c'est plus approprié pour le C++. Vous pourriez également vous intéresser à robodoc, même si je pense que le rasoir d'Occam vous dira plutôt d'opter pour Doxygen.

En ce qui concerne la documentation, je n'ai jamais été moi-même un fan de documentation, mais que cela me plaise ou non, avoir plus de documentation bat toujours sans avoir de documentation. Je mettrais la documentation de l'API dans le fichier d'en-tête, et la documentation de l'implémentation dans l'implémentation (va de soi, n'est-ce pas?). :) De cette façon, les IDE ont la possibilité de le ramasser et de le montrer pendant l'auto-complétion (Eclipse le fait pour JavaDocs, par exemple, peut-être aussi pour doxygen?), Ce qui ne devrait pas être sous-estimé. JavaDoc a cette bizarrerie supplémentaire qu'il utilise la première phrase (c'est-à-dire jusqu'au premier arrêt complet) comme une brève description, ne sais pas si Doxygen fait cela, mais si c'est le cas, il doit être pris en compte lors de l'écriture de la documentation. Avoir beaucoup de documentation risque d'être obsolète, cependant, en gardant la documentation proche du code, les gens auront une chance de la garder à jour, donc vous devriez la garder dans la source/l'en-tête des dossiers. Ce qui ne devrait pas être oublié cependant est la production de documentation. Oui, certaines personnes utiliseront la documentation directement (via l'EDI ou autre, ou simplement en lisant le fichier d'en-tête), mais certaines personnes préfèrent d'autres moyens, donc vous devriez probablement mettre en ligne votre documentation API régulièrement mise à jour. , ainsi que peut-être produire des fichiers man si vous ciblez des développeurs * nix.

Voilà mes deux cents.