Documentation
En règle générale, les projets du style gtkmm utilisent Doxygen, qui lit les commentaires dans un format particulier et génère une documentation HTML. Vous pouvez écrire ces commentaires doxygen directement dans les fichiers d'en-tête.
- G.VII.I. Réutilisation de la documentation C
- G.VII.II. Structure de construction de la documentation
G.VII.I. Réutilisation de la documentation C
You might wish to reuse documentation that exists for the C library that you are wrapping. GTK-style C libraries typically use gtk-doc and therefore have source code comments formatted for gtk-doc and some extra documentation in .sgml and .xml files. The docextract_to_xml.py script, from glibmm's tools/defs_gen directory, can read these files and generate an .xml file that gmmproc can use to generate doxygen comments. gmmproc will even try to transform the documentation to make it more appropriate for a C++ API.
Par exemple,
./docextract_to_xml.py -s ~/checkout/gnome/gtk+/gtk/ -s ~/checkout/gnome/gtk+/docs/reference/gtk/ > gtk_docs.xml
Cette transformation automatique n'est pas toujours appropriée ; vous serez amené à rédiger un texte pour des fonctions membres particulières. Vous pouvez faire cela en copiant le nœud XML concernant la fonction du fichier something_docs.xml vers le fichier something_docs_override.xml et en modifiant son contenu.
G.VII.II. Structure de construction de la documentation
Si vous avez copié l'arborescence des squelettes sources de mm-common et substitué le texte à remplacer, vous disposez déjà de fichiers Makefile.am et Doxyfile.in convenables. Avec le paramétrage de construction de mm-common, la liste des fichiers d'entrée Doxygen n'est pas définie dans le fichier de configuration Doxygen, mais passée de make à l'entrée standard de doxygen. La liste des fichiers en entrée est définie par la variable doc_input du fichier Makefile.am.