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:
-
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).
-
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+.
-
Gerando os arquivos "template". gtkdoc-mktmpl cria uma quantidade de arquivos no subdiretório tmpl/, usando a informação coletada na primeira etapa. (Note que ele pode ser executado repetidas vezes e vai tentar garantir que nenhuma documentação será perdida, jamais.)
Desde o GTK-Doc 1.9, os modelos ("templates") podem ser evitados. Nós encorajamos as pessoas a manter a documentação no código. gtkdocize possui suporte a uma opção --flavour no-tmpl que escolhe um makefile que ignora totalmente o uso de tmpl. Se você nunca alterou o arquivo em tmpl manualmente, por favor remova o diretório (ex.: do sistema de controle de versão).
-
Gerando o SGML/XML e HTML/PDF. gtkdoc-mkdb transforma os arquivos modelos em arquivos SGML ou XML no subdiretório sgml/ ou 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. Nós recomendamos usar o Docbook XML.
gtkdoc-mkhtml transforma os arquivos SGML/XML em arquivos HTML no subdiretório html/. Da mesma forma, gtkdoc-mkpdf transforma os arquivos SGML/XML em um documento PDF chamado <pacote>.pdf.
Arquivos nos diretórios sgml/ ou xml/ e html/ são sempre sobrescritos. Não devem ser editados manualmente.
-
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).