¿Cómo funciona GTK-Doc?

GTK-Doc funciona usando documentación de las funciones ubicadas dentro de los archivos de fuentes en bloques de comentarios especialmente formateados, o documentación añadida a los archivos de plantillas que GTK-Doc usa (aunque debe notar que GTK-Doc sólo documentará las funciones declaradas en los archivos de cabecera; no produce salida para funciones estáticas).

GTK-Doc consiste en un número de scripts en Perl, cada uno realiza un paso diferente en el proceso.

Existen 5 pasos importantes en el proceso:

  1. Escribir la documentación. El autor rellena los archivos de fuentes con la documentación para cada función, macro, unión, etc. (En el pasado la información se introducía en archivos de plantillas, lo que ya no se recomienda).

  2. Obtener información acerca del código. gtkdoc-scan analiza los archivos de cabecera del código buscando declaraciones de funciones, macros, enumeraciones, estructuras y uniones. Crea el archivo <module>-decl-list.txt que contiene una lista de las declaraciones, ubicándolas en secciones de acuerdo con el archivo de cabecera en el que están. Durante la primera ejecución este archivo se copia en <module>-sections.txt. El autor puede reordenar las secciones y el orden de las declaraciones en ellas, para producir la salida que quiere. El segundo archivo que genera es <module>-decl.txt. Este archivo contiene las declaraciones completas que encontró el análisis. Si por alguna razón quisiese que algunos símbolos apareciesen en los documentos, donde el análisis no puede encontrar la declaración completa o la declaración debería aparecer de forma diferente, puede introducir entradas de forma similar a las que hay en <module>-decl.txt dentro de <module>-overrides.txt.

    gtkdoc-scangobj también se puede usar para consultar dinámicamente una biblioteca sobre cualquiera de las subclases GObject que exporta. Guarda información sobre la posición de cada objeto en la jerarquía de clases y sobre cualquier propiedad de GObject y las señales que proporciona.

    gtkdoc-scanobj no se debería usar más. Se necesitó en el pasado, cuando GObject todavía era GtkObject dentro de GTK+.

  3. Generar el XML y el HTML/PDF.gtkdoc-mkdb convierte los archivos de plantilla en archivos SGML o XML en la subcarpeta xml/. Si el código fuente contiene documentación de funciones, usando los bloques especiales de comentarios, entonces se mezclarán aquí. Si no se usan archivos tmpl sólo obtiene los documentos de los fuentes y los datos obtenidos en introspección.

    gtkdoc-mkhtml convierte los archivos XML en archivos HTML en la subcarpeta html/. De la misma forma gtkdoc-mkpdf convierte los archivos XML en un documento PDF llamado <paquete>.pdf.

    Los archivos en las carpetas xml/ y html/ y siempre se sobrescriben. Nunca se deben editar directamente.

  4. Arreglar referencias cruzadas entre documentos. Después de instalar los archivos HTML se puede ejecutar gtkdoc-fixxref para arreglar cualquier referencia cruzada entre documentos separados. Por ejemplo, la documentación GTK+ contiene muchas referencias cruzadas a tipos documentados en el manual de GLib. Al crear los archivadores «tarball» para su distribución, gtkdoc-rebase convierte todos los enlaces externos en enlaces web. Al instalar la documentación distribuida (pregenerada) la misma aplicación intentará convertir de nuevo los enlaces, esta vez a enlaces locales (donde esa documentación está instalada).