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

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/ > gtk_docs.xml

Because this automatic transformation is not always appropriate, you might want to provide hand-written text for a particular method. You can do this by copying the XML node for the function from your something_docs.xml file to the something_docs_override.xml file and changing the contents. Alternatively you can write your own documentation in the .hg file.

G.VII.II. Structure de construction de la documentation

If you copied the skeleton source tree in mm-common and substituted the placeholder text, then you will already have suitable meson.build and Doxyfile.in files in the doc/reference/ directory. You probably need to modify the tag_file_modules variable in meson.build, though. With the mm-common build setup, the list of Doxygen input files is not defined in the Doxygen configuration file, but passed along from meson/ninja to the standard input of doxygen.