Como o GTK-Doc funciona?

O GTK-Doc funciona usando a documentação de funções colocadas dentro dos arquivos fonte em blocos de comentários especialmente formatados ou documentação adicionada aos arquivos modelo que o GTK-Doc usa (apesar disso, note que o GTK-Doc vai documentar apenas funções que são declaradas em arquivos de cabeçalho; ele não irá produzir saída para funções estáticas).

GTK-Doc consiste de um número de scripts perl, cada um executando uma etapa diferente no processo.

Há 5 etapas principais no processo:

  1. Escrevendo a documentação. O autor preenche os arquivos fonte com a documentação para cada função, macro, union, etc. (Anteriormente, a informação era inserida em arquivos de modelo gerados, o que não é mais recomendado).

  2. Juntando informação sobre o código. gtkdoc-scan varre os arquivos de cabeçalho do código buscando por declarações de funções, macros, enums, structs e unions. Ele cria o arquivo <módulo>-decl-list.txt contendo uma lista de declarações, inserindo-as em seções da acordo com o arquivo de cabeçalho no qual se encontram. Na primeira execução, este arquivo é copiado para <módulo>-sections.txt. O autor pode reorganizar as seções, e a ordem das declarações dentro delas, para produzir a ordem final desejada. O segundo arquivo que ele gera é <módulo>-decl.txt. Este arquivo contém as declarações completas encontradas pela varredura. Se por algum motivo se queira que alguns apareçam nos documentos, no qual declarações completas não puderam ser encontradas pela varredura ou a declaração deveria aparecer de outra forma, pode-se colocar entidades similares aos do <módulo>-decl.txt no <módulo>-overrides.txt.

    gtkdoc-scangobj também pode ser usado para consultar dinamicamente uma biblioteca sobre qualquer subclasse GObject que ele exporta. Ele salva informações sobre cada posição do objeto na hierarquia de classe e sobre quaisquer propriedades GObject e sinais que ela fornece.

    gtkdoc-scanobj não deveria mais ser usada. Ele era necessário no passado, quando GObject ainda era GtkObject dentro do gtk+.

  3. Gerando o XML e HTML/PDF. gtkdoc-mkdb transforma os arquivos modelos em arquivos XML no subdiretório xml/. Se o código fonte contém documentação nas funções, usando os blocos de comentários especiais, ela é mesclada aqui. Se não há arquivos tmpl sendo usados, ele apenas lê documentos dos dados de introspecção e dos fontes.

    gtkdoc-mkhtml transforma os arquivos XML em arquivos HTML no subdiretório html/. Da mesma forma, gtkdoc-mkpdf transforma os arquivos XML em um documento PDF chamado <pacote>.pdf.

    Arquivos nos diretórios xml/ e html/ são sempre sobrescritos. Não devem ser editados manualmente.

  4. Consertando referências cruzadas entre documentos. Após a instalação dos arquivos HTML, gtkdoc-fixxref pode ser executado para consertar referências cruzadas entre documentos separados. Por exemplo, a documentação do GTK+ contém muitas referências cruzadas a tipos documentados no manual do GLib. Ao criar um tarball fonte para distribuição, gtkdoc-rebase transforma todos os links externos em web-links. Ao instalar documentações distribuídas (geradas previamente), o mesmo aplicativo vai tentar transformar links de volta para links locais (onde aquelas documentações estão instaladas).