Documentation du fichier d'en-tête C / C ++ [fermée]

Question

Quelle est selon vous 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 tout vu, de pratiquement aucune documentation (reposant sur une documentation externe) à de grandes spécifications d'invariants, de paramètres valides, de valeurs de retour, etc. Je ne sais pas exactement ce que je préfère, une grande documentation est agréable, car vous avez toujours accès à En revanche, dans votre éditeur, un fichier d’en-tête avec une documentation très brève peut souvent afficher une interface complète sur une ou deux pages de texte, offrant ainsi une bien meilleure vue 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 au 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 java doc-style, mais y at-il d’autres conventions et outils que je devrais connaître avant de passer à la documentation de style javadoc?

Answer 1

D'habitude, je mets la documentation de l'interface (paramètres, valeur de retour, que fait la fonction ) dans le fichier d'interface (.h), ainsi que la documentation relative à l'implémentation ( comment la fonction fait) dans le fichier d'implémentation (.c, .cpp, .m).

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

L'outil que j'utilise est Doxygen.

Answer 2

1. J'aurais définitivement de la documentation dans les fichiers d'en-tête eux-mêmes. Cela améliore grandement le débogage d'avoir les informations à côté du code, et non dans des documents séparés. En règle générale, je documenterais l'API (valeurs de retour, arguments, changements d'état, etc.) à côté du code, ainsi que 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 le placer avec le code, car il référence généralement plusieurs classes à la fois).

2. Doxygen convient à mon expérience.

Answer 3

Je pense que Doxygen est la plate-forme la plus courante pour générer de la documentation et, autant que je sache, elle est plus ou moins capable de couvrir la notation JavaDoc (non limitée à bien sûr). J'ai utilisé doxygen pour C, avec des résultats satisfaisants, je pense cependant que cela convient mieux au C ++. Vous voudrez peut-être aussi vous pencher sur robodoc, même si je pense que Razor d’Occam vous dira de choisir plutôt Doxygen.

En ce qui concerne la quantité de documentation, je n'ai jamais été un fan de documentation, mais que cela me plaise ou non, avoir plus de documentation est toujours préférable à l'absence 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 (il va sans dire, n'est-ce pas?). :) Ainsi, les IDE auront la chance de le récupérer et de le montrer lors de l'auto-complétion (Eclipse le fait pour JavaDocs, par exemple, peut-être aussi pour doxygen?), Qui ne doit pas être sous-estimé. Cette particularité supplémentaire de JavaDoc est qu’elle utilise la première phrase (c’est-à-dire jusqu’au premier point) comme brève description. Je ne sais pas si Doxygen le fait, mais dans l’affirmative, elle devrait être prise en compte lors de la rédaction de la documentation.

Le fait d’avoir beaucoup de documentation risque de devenir obsolète. Cependant, garder cette documentation près du code donnera aux utilisateurs une chance de le garder à jour. Vous devez donc absolument le conserver dans les fichiers source / en-tête. . Ce qu’il ne faut pas oublier, c’est la production de documentation. Oui, certaines personnes utiliseront directement la documentation (via l'EDI ou autre, ou simplement en lisant le fichier d'en-tête), mais d'autres préfèrent d'autres méthodes. Vous devriez donc probablement envisager de mettre en ligne votre documentation d'API (mise à jour régulièrement), toutes agréables et pouvant être consultées. , ainsi que peut-être produire des fichiers man si vous ciblez des développeurs basés sur * nix.

Ce sont mes deux cents.

Answer 4

Mettez suffisamment dans le code pour qu'il soit autonome. Presque tous les projets où j'ai participé et où la documentation était séparée, sont devenus obsolètes ou n'ont pas été finalisés, en partie parce que s'il s'agit d'un document séparé, il devient une tâche distincte, en partie parce que la direction ne l'a pas autorisé. en budgétisation. La documentation en ligne dans le cadre du flux fonctionne beaucoup mieux selon mon expérience.

Rédigez la documentation sous une forme que la plupart des éditeurs reconnaissent 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 5

gtk-doc pourrait vous intéresser. Il peut être & Difficile de configurer et d’utiliser & Quot; mais vous pouvez obtenir une belle documentation sur l'API à partir du code source, ressemblant à ceci:

Fonctions utilitaires de chaîne