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
Vous pouvez souhaiter réutiliser la documentation existante de la bibliothèque C que vous êtes en train d'habiller. Les bibliothèques du style C GTK utilisent généralement gtk-doc ; les commentaires de leur code source est donc formaté pour gtk-doc avec de la documentation supplémentaire dans des fichiers .tmpl. Le script docextract_to_xml.py, situé dans le répertoire codegen de pygobject, est capable de lire ces fichiers et de générer un fichier .xml que gmmproc peut utiliser pour générer à son tour des commentaires doxygen. gmmproc essaye même de transformer la documentation pour mieux l'adapter à une API C++.
Par exemple,
./docextract_to_xml.py -s /gnome/head/cvs/gtk+/gtk/ \ -s /gnome/head/cvs/gtk+/docs/reference/gtk/tmpl/ > 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.