Contrôle du résultat

Une exécution de GTK-Doc produit des fichiers de compte-rendu dans le répertoire de documentation. Ces fichiers sont nommés : <package>-undocumented.txt, <package>-undeclared.txt et <package>-unused.txt. Tous ces fichiers texte peuvent être lus et post-traités facilement.

Le fichier <package>-undocumented.txt commence avec un résumé du sujet couvert par la documentation. Suivent deux sections séparées par des lignes blanches. La première section liste les symboles non documentés ou incomplets. La seconde section fait de même pour les documentations de sections. Les éléments incomplets sont ceux qui possèdent une documentation mais auxquels, par exemple, un paramètre a été ajouté.

Le fichier <package>-undeclared.txt liste les symboles contenus dans le fichier <package>-sections.txt mais non trouvés dans les fichiers sources. Vérifiez s'ils n'ont pas été supprimés ou mal orthographiés.

Le fichier <package>-unused.txt liste les noms des symboles pour lesquels l'analyseur GTK-Doc a trouvé de la documentation mais ne sait pas où la placer. Cela signifie que le symbole n'a pas encore été ajouté au fichier <package>-sections.txt.

Activez ou ajoutez la ligne TESTS=($GTKDOC_CHECK) dans le fichier Makefile.am. Si la version installée de GTK-Doc est supérieure à 1.9, des contrôles de validité seront lancés pendant l'exécution de make check.

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 gtkdoc to keep the intermediate scanner file for further analysis, by running it as GTK_DOC_KEEP_INTERMEDIATE=1 make.