Controlling the result

A GTK-Doc run generates report files inside the documentation directory. The generated files are named: <package>-undocumented.txt, <package>-undeclared.txt and <package>-unused.txt. All those are plain text files that can be viewed and postprocessed easily.

The <package>-undocumented.txt file starts with the documentation coverage summary. Below are two sections divided by blank lines. The first section lists undocumented or incomplete symbols. The second section does the same for section docs. Incomplete entries are those, which have documentation, but where e.g. a new parameter has been added.

The <package>-undeclared.txt file lists symbols given in the <package>-sections.txt but not found in the sources. Check if they have been removed or if they are misspelled.

The <package>-unused.txt file lists symbol names, where the GTK-Doc scanner has found documentation, but does not know where to put it. This means that the symbol has not yet been added to the <package>-sections.txt file.

Enable or add the TESTS=$(GTKDOC_CHECK) line in If at least GTK-Doc 1.9 is installed, this will run sanity checks during make check run.

One can also look at the files produced by the source code scanner: <package>-decl-list.txt and <package>-decl.txt. The first one can be compared with the section file if that is manually maintained. The second lists all declarations from the headers. If a symbol is missing one could check if this file contains it.

If the project is GObject based, one can also look into the files produced by the object scanner: <package>.args.txt, <package>.hierarchy.txt, <package>.interfaces.txt, <package>.prerequisites.txt and <package>.signals.txt. If there are missing symbols in any of those, one can ask GTK-Doc to keep the intermediate scanner file for further analysis, by running it as GTK_DOC_KEEP_INTERMEDIATE=1 make.