Dokumentace

Obecně používají projekty ve stylu gtkmm Doxygen, který čte speciálně formátované komentáře jazyka C++ a generuje z nich dokumentaci v HTML. Tyto komentáře můžete zapisovat přímo do hlavičkových souborů.

G.7.1. Recyklace dokumentace ke knihovnám C

Můžete si přát využít dokumentaci, která již existuje pro knihovny jazyka C, které jsou pro C++ obalené. Tyto knihovny ve stylu GTK typicky používají gtk-doc a proto mají komentáře ve zdrojovém kódu formátované pro gtk-doc a k tomu nějakou doplňující dokumentaci v souborech .sgml a .xml. Skript docextract_to_xml.py ze složky tools/defs_gen umí tyto soubory číst a vygenerovat soubor .xml, který může gmmproc použít k vygenerování komentářů pro doxygen. gmmproc se navíc pokusí provést v dokumentaci nějaké změny, aby lépe odpovídala API C++.

Například

./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.7.2. Struktura pro sestavení dokumentace

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.