included"> ]> Manual do GTK-Doc 1.24.1 Manual de usuário para desenvolvedores com instruções do uso do GTK-Doc. Chris Lyttle
chris@wilddev.net
Dan Mueth
d-mueth@uchicago.edu
Stefan Sauer (Kost)
ensonic@users.sf.net
Projeto GTK-Doc
gtk-doc-list@gnome.org
 2000, 2005 Dan Mueth e Chris Lyttle 2007-2019 Stefan Sauer (Kost) Permissão concedida para copiar, distribuir e/ou modificar este documento sob os termos da Licença de Documentação Livre GNU (GNU Free Documentation License), Versão 1.1 ou qualquer versão mais recente publicada pela Free Software Foundation; sem Seções Invariantes, Textos de Capa Frontal, e sem Textos de Contracapa. Você pode encontrar uma cópia da licença está inclusa. Muitos dos nomes usados por empresas para distinguir seus produtos e serviços são reivindicados como marcas registradas. Onde esses nomes aparecem em qualquer documentação do GNOME e os membros do Projeto de Documentação do GNOME estiverem cientes dessas marcas registradas, os nomes aparecerão impressos em letras maiúsculas ou com iniciais em maiúsculas. 1.33.0 1 out 2020 ss versão gtk4 1.32.1 15 ago 2019 ss versão de desenvolvimento 1.32 15 ago 2019 ss lançamento de correção de erros 1.31 05 ago 2019 ss refatoramentos e mais cobertura de testes 1.30 08 maio 2019 ss mais cobertura de testes 1.29 28 ago 2018 ss correções de erros 1.28 24 mar 2018 ss correções de erros 1.27 07 dez 2017 ss ajustes do porte para Python 1.26 11 ago 2017 ss portadas todas ferramentas de perl/bash para Python 1.25 21 mar 2016 ss correção de erros, limpezas de testes 1.24 29 maio 2015 ss correção de erros 1.23 17 maio 2015 ss correção de erros 1.22 07 maio 2015 ss correção de erros, desativadas funcionalidades obsoletas 1.21 17 jul 2014 ss correção de erros, desativadas funcionalidades obsoletas 1.20 14 fev 2014 ss correção de erros, suporte a markdown, melhorias no estilo 1.19 05 jun 2013 ss correção de erros 1.18 14 set 2011 ss correção de erros, aceleração, suporte a markdown 1.17 26 Fev 2011 sk atualização de correção de erro urgente 1.16 14 jan 2011 sk correção de erros, melhorias no layout 1.15 21 maio 2010 sk correção de erros e regressões 1.14 28 mar 2010 sk Correção de erro e melhorias na performance 1.13 18 dez 2009 sk atualização de tarball defeituoso 1.12 18 dez 2009 sk novas funcionalidades da ferramenta e correção de erros 1.11 16 nov 2008 mal migração do GNOME doc-utils Marcelo Rodrigues marcelopires@mmsantos.com.br 2010 Marcelo Rodrigues Rafael Fontenelle rafaelff@gnome.org 2013-2021 Rafael Fontenelle Leônidas Araújo leorusvellt@hotmail.com 2022-2023 Leônidas Araújo Introdução Este capítulo introduz GTK-Doc e dá um visão geral do que ele é e como ele é usado. O que é GTK-Doc? GTK-Doc é usado para documentar código C. Ele é tipicamente usado para documentar a API pública das bibliotecas, como as bibliotecas baseadas no Glib. Mas ele também pode ser usado para documentar código de aplicativos. Como o GTK-Doc funciona? O GTK-Doc funciona lendo blocos de comentários formatados especialmente para esse fim, inseridos nos arquivos de origem, para documentar símbolos como funções, macros, structs, enums, etc. (observe, porém, que para a maioria dos tipos de símbolos, o GTK-Doc documentará apenas os símbolos declarados nos arquivos de cabeçalho; por exemplo, ele não produzirá saída para funções estáticas). O GTK-Doc também lê arquivos de modelo, onde a documentação pode ser adicionada. GTK-Doc consiste em um número de programas, cada um executando uma etapa diferente no processo. Há etapas principais são: Escrita da documentação. O autor preenche os arquivos fonte com a documentação para cada função, macro, structs ou unions, etc. Coleta de 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 quiser que alguns símbolos apareçam nos documentos, nos quais 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 deve mais ser usado. Ele era necessário no passado, quando GObject ainda era GtkObject dentro do GTK. Geração do XML e do HTML/PDF. gtkdoc-mkdb transforma os arquivos modelos em arquivos XML no subdiretório xml/. Se o código-fonte contém documentação para símbolos, 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. Correção de 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). Obtendo GTK-Doc Requisitos python 2/3 – os scripts principais são escritos em Python. xsltproc – o processador de xslt do libxslt xmlsoft.org/XSLT/ docbook-xsl – as folhas de estilo xsl de docbook sourceforge.net/projects/docbook/files/docbook-xsl Um dentre source-highlight, highlight ou vim – opcional - usado para destaque de sintaxe de exemplos Sobre GTK-Doc Historicamente, o GTK-Doc foi usado para gerar arquivos de modelo a partir do código-fonte. Esses arquivos de modelo poderiam ser usados pelos desenvolvedores para inserir a documentação da API. Essa abordagem era bastante inconveniente porque exigia manter os arquivos gerados sob controle de versão. Desde o GTK-Doc 1.9, tornou-se possível colocar todas as informações da API em comentários no fonte, o que tornou o suporte ao modelo obsoleto. Na versão 1.26 suporte ao modelo foi removido. (CORRIJA-ME) (autores, páginas web, lista de discussão, licença, planos futuros, comparação com outros sistemas similares.) Sobre este manual (CORRIJA-ME) (pra quem ele serve, onde você pode obtê-lo, licença) Configurando o projeto Este capítulo descreve os passos necessários para integrar o GTK-Doc ao seu projeto. A integração do GTK-Doc em um projeto inclui as seguintes etapas: Preparação da estrutura de diretórios e criação dos arquivos de configuração necessários para sua documentação do GTK-Doc (consulte Preparando o esqueleto de uma documentação). Ajuste do sistema de compilação para compilar sua documentação usando as ferramentas do GTK-Doc. Há suporte a vários sistemas de compilação, neste manual descrevemos como integrar o GTK-Doc com Autotools, CMake e Makefiles simples. Adição de arquivos específicos do GTK-Doc para o controle de versão e decisão de quais arquivos ignorar (veja Integração com sistemas de controle de versão). As seções a seguir presumem que trabalhamos em um projeto chamado meep. Este projeto contém dois pacotes (ou módulos), uma biblioteca chamada libmeep e um aplicativo de usuário final chamado meeper. Preparando o esqueleto de uma documentação Uma convenção comum é colocar a documentação em uma pasta chamada docs dentro do seu diretório de projeto de nível superior. Costumamos distinguir entre a documentação de referência destinada aos programadores e um manual do usuário destinado aos usuários-finais. Novamente a convenção é ter pastas separadas para ambos. Geralmente, colocamos a documentação de referência em uma pasta chamada reference e o manual do usuário final em uma pasta chamada help. De acordo com a convenção acima, a documentação do nosso pacote libmeep seria colocada em: docs/reference/libmeep. Para pacotes com apenas uma biblioteca ou aplicativo, a documentação também pode ser colocada diretamente em docs/reference. Não é obrigatório usar a convenção acima, mas se você optar por usar uma estrutura de diretórios diferente, deverá ajustar a configuração do sistema de compilação para que corresponda à estrutura do diretório. Nas seções a seguir, vamos presumir uma estrutura de diretórios para o nosso projeto meep que usa as convenções acima. Exemplo de estrutura de diretórios de projeto <emphasis>meep</emphasis> meep/ docs/ reference/ # documentação de referência libmeep/ meeper/ help/ # opcional: manual de usuário meeper/ src/ libmeep/ meeper/ Integração com Autotools A integração do GTK-Doc em um sistema de compilação baseado em autotools requer as seguintes etapas: Certificar-se de que gtkdocize seja executado uma vez antes do script configure. Se um script autogen.sh estiver presente, ajuste-o para verificar o GTK-Doc e adicione uma chamada ao gtkdocize. O principal objetivo do gtkdocize é fazer com que o arquivo Makefile gtk-doc.make e o arquivo de definição de macro gtk-doc.m4 estejam disponíveis para a compilação sistema, seja copiando ou vinculando-o ao projeto. Adicionar as macros autoconf necessárias ao configure.ac para ativar o GTK-Doc em seu sistema de compilação para permitir a configuração do GTK-Doc através do script configure gerado. Entre outros, registra a opção --enable-gtk-doc com o script configure. Criar um script automake para cada aplicativo ou biblioteca em seu projeto. No exemplo usado nesta documentação, esta etapa se aplica tanto a meeper quanto a libmeep. Nas seções a seguir, executaremos as etapas acima na ordem inversa. Começamos com os scripts automake e vamos trabalhando até o configure.ac e autogen.sh. Então, mostramos como habilitar o Gtk-Doc no sistema de compilação e como compilar a documentação. Integração com automake Primeiro copie o Makefile.am do subdiretório do exemplo do gtkdoc-sources para o diretório da documentação de referência do seu projeto (por exemplo, ./docs/reference/<pacote>). Uma cópia local deveria estar disponível sob, por exemplo, /usr/share/doc/gtk-doc-tools/examples/Makefile.am. Se você tiver múltiplos pacotes de documentação, repita isso para cada um. Não se esqueça de adicionar cada Makefile.am à macro AC_CONFIG_FILES em configure.ac. Para docs/reference/libmeep/Makefile.am você precisará adicionar a entrada docs/reference/libmeep/Makefile para AC_CONFIG_FILES. Exemplo de estrutura de diretório com <filename>Makefiles.am</filename> meep/ docs/ reference/ # documentação de referência libmeep/ Makefile.am meeper/ Makefile.am help/ # opcional: manual de usuário meeper/ src/ libmeep/ meeper/ Em seguida, você precisa personalizar os Makefiles copiados e fornecer valores para os vários parâmetros em cada Makefile.am. Todas as configurações têm um comentário sobre elas que descreve seu propósito e como personalizar a configuração. A maioria das configurações são usadas para fornecer opções extras para as respectivas ferramentas às quais elas se aplicam. Cada ferramenta tem uma variável na forma (por exemplo, a ferramenta gtkdoc-mkhtml tem uma opção chamada MKHTML_OPTIONS). Todas as ferramentas têm suporte a pra listar os parâmetros disponíveis. A lista a seguir explica as opções mais relevantes. Verifique o exemplo Makefile.am para opções adicionais. é usado para fornecer o nome do pacote que está sendo documentado (por exemplo, meeper ou libmeep). é usado para especificar a localização do diretório fonte que o GTK-Doc pesquisa na documentação da API. Isso geralmente será DOC_SOURCE_DIR=$(top_srcdir)/src ou um subdiretório desse diretório. e são usados para dependências. Cada opção pega um arquivo glob (por exemplo, HFILE_GLOB=$(top_srcdir)/src/*.c). A documentação será recompilada se qualquer um dos arquivos correspondentes for alterado. permite especificar arquivos de cabeçalho extras para incluir ao verificar a documentação da API, que não são encontrados em DOC_SOURCE_DIR (por exemplo, EXTRA_HFILES=$(top_srcdir}/contrib/extra.h). permite especificar arquivos ou diretórios de cabeçalho a serem ignorados ao verificar a documentação da API. Use o nome de base do arquivo ou diretório (por exemplo, IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder). permite especificar arquivos de imagens que serão copiados para o diretório html/ da documentação gerada. Se a documentação da API incluir imagens, elas precisam ser adicionadas a essa opção (por exemplo, HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png). permite especificar arquivos extras incluídos por $(DOC_MAIN_SGML_FILE) (por exemplo, content_files=running.xml building.xml changes-2.0.xml). permite especificar arquivos onde as abreviaturas gtk-doc como #GtkWidget são expandidas (por exemplo, expand_content_files=running.xml). Integração com autoconf A integração com autoconf é muito simples e inclui uma etapa obrigatória e uma etapa adicional opcional (mas recomendada). O primeiro passo é adicionar a macro GTK_DOC_CHECK ao seu script configure.ac. Isso registra várias opções de configuração para habilitar o GTK-Doc e permite definir argumentos padrão para gtkdocize. Certifique-se de que a macro GTK_DOC_CHECK não esteja recuada. A macro deve começar no início da linha e não deve começar com espaço em branco. O segundo passo é adicionar o AC_CONFIG_MACRO_DIR(m4) ao seu configure.ac. Isso não é necessário, mas ajuda o gtkdocize a copiar automaticamente a definição da macro (por exemplo, gtk-doc.m4) que contém a macro GTK_DOC_CHECK para o diretório de macro do seu projeto. Sem isso, a macro GTK_DOC_CHECK pode não ser encontrada e você precisaria informar explicitamente à ferramenta aclocal onde encontrar o arquivo de definição de macro. Integração mínima com autoconf # recomendado: defina o diretório m4 AC_CONFIG_MACRO_DIR(m4) # opcional: registre gtk-doc no configure GTK_DOC_CHECK([1.28]) O exemplo acima funciona, mas exigirá que todos os desenvolvedores tenham o gtk-doc instalado. Uma maneira melhor é tornar a documentação opcional, conforme mostrado no próximo exemplo: Integração com dependência opcional do gtk-doc m4_ifdef([GTK_DOC_CHECK], [ # recomendado: defina diretório m4 AC_CONFIG_MACRO_DIR(m4) # opcional: registre gtk-doc no configure GTK_DOC_CHECK([1.28]) ],[ AM_CONDITIONAL([ENABLE_GTK_DOC], false) ]) O primeiro argumento é usado para verificar a versão do Gtk-Doc em tempo de compilação. O segundo argumento é opcional, sendo usado por gtkdocize. A macro GTK_DOC_CHECK também adiciona várias opções de configuração: --with-html-dir=CAMINHO : caminho para as documentações instaladas --enable-gtk-doc : usa gtk-doc para compilar documentação [padrão=não] --enable-gtk-doc-html : compila documentação em formato html [padrão=sim] --enable-gtk-doc-pdf : compila documentação em formato pdf [padrão=não] GTK-Doc está desabilitado por padrão! Lembre-se de passar a opção à próxima execução do configure. Do contrário, uma documentação gerada previamente é instalada (o que faz sentido para usuários, mas não para desenvolvedores). Após todas as alterações do configure.ac serem feitas, atualize o arquivo configure. Isso pode ser feito executando novamente autogen.sh. Integração com autogen A maioria dos projetos tem um script autogen.sh para configurar a infraestrutura de compilação após o checkout do projeto sistema de um controle de versão (como git ou svn). GTK-Doc vêm com um script chamado gtkdocize que pode ser usado para copiar os arquivos necessários pelo Gtk-Doc para o diretório fonte. Ele deve ser executado antes de autoreconf, autoheader, automake or autoconf. Executando gtkdocize no autogen.sh gtkdocize || exit 1 Executa condicionalmente gtkdocize no autogen.sh GTKDOCIZE=$(which gtkdocize 2>/dev/null) if test $? -ne 0; then echo "No gtk-doc support found. You can't build the docs." else $GTKDOCIZE || exit 1 fi Ao executar gtkdocize, ele copia gtk-doc.make para a raiz do seu projeto (ou qualquer diretório especificado pela opção ). gtkdocize verifica seu script configure.ac para GTK_DOC_CHECK. A macro GTK_DOC_CHECK pode ser usada para passar parâmetros extras para o script gtkdocize. Alternativamente, argumentos adicionais também podem ser passados para gtkdocsize por meio da variável de ambiente GTKDOCIZE_FLAGS ou especificando-os diretamente ao gtkdocsize no autogen.sh. Executando GTK-Doc a partir do sistema de compilação Após as etapas anteriores, é hora de executar a compilação. Primeiro, nós queremos executar novamente o autogen.sh. Se este script executa o configure para você, então forneça a este a opção . Do contrário, execute manualmente configure com esta opção em seguida. A primeira execução do make cria vários arquivos adicionais nos diretórios de documentação. Os importantes são: <pacote>.types, <pacote>-docs.xml (no passado, .sgml), <pacote>-sections.txt. Executando a compilação da documentação ./autogen.sh --enable-gtk-doc make Agora você pode apontar seu navegador para docs/reference/<pacote>/index.html . Com esta configuração inicial, você verá apenas um documento muito simples. O próximo capítulo ensinará como adicionar documentação da API ao seu código por meio de blocos de comentários especiais. O capítulo seguinte depois introduz arquivos adicionais e mostra como editar o modelo mestre para adicionar capítulos e seções adicionais aos seus arquivos de documentação. Integração com sistemas de compilação CMake GTK-Doc agora fornece um módulo GtkDocConfig.cmake (e o module GtkDocConfigVersion.cmake correspondente). Ele fornece um comando gtk_doc_add_module que você pode usar em seu arquivo CMakeLists.txt. O exemplo a seguir mostra como usar este comando. Exemplo de uso do GTK-Doc no CMake find_package(GtkDoc 1.25 REQUIRED) # Cria o alvo doc-libmeep. gtk_doc_add_module( libmeep ${CMAKE_SOURCE_DIR}/libmeep XML meep-docs.xml LIBRARIES libmeep ) # Compila doc-libmeep como parte do alvo padrão. Sem isso, você precisaria # executar explicitamente algo como `make doc-libmeep` para compilar os # documentos. add_custom_target(documentation ALL DEPENDS doc-libmeep) # Instala os documentos. (Isso presume que você está usando o módulo # GNUInstallDirs do CMake para definir a variável CMAKE_INSTALL_DOCDIR # corretamente). install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html DESTINATION ${CMAKE_INSTALL_DOCDIR}) Integração com makefiles simples ou outros sistemas de compilação Neste caso, não se deseja usar o automake e, portanto, gtk-doc.mak. Será necessário chamar as ferramentas do gtkdoc na ordem correta nos makefiles devidos (ou outras ferramentas de compilação). Etapas de compilação da documentação DOC_MODULE=meep // fontes foram alterados gtkdoc-scan --module=$(DOC_MODULE) <source-dir=> gtkdoc-scangobj --module=$(DOC_MODULE) gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<source-dir> // arquivos xml foram alterados mkdir html cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html Será necessário olhar no Makefile.am e no gtk-doc.mak para obter as opções extras necessárias. Integração com sistemas de controle de versão Como uma regra de ouro, são aqueles arquivos que você edita que devem entrar no controle de versão. Para projetos normais, esses são os arquivos: <pacote>.types, <pacote>-docs.xml (no passado, .sgml), <pacote>-sections.txt, Makefile.am. Arquivos nos diretórios xml/ e html/ não devem entrar no controle de versão. Da mesma forma, não devem entrar arquivos .stamp. Documentando o código GTK-Doc usa comentários do código-fonte com uma sintaxe especial para documentação do código. Além disso, ele obtém informações sobre a estrutura do seu projeto a partir de outros fontes. Na próxima seção, você vai descobrir todas as informações sobre a sintaxe dos comentários. O verificador do GTK-Doc sabe lidar com a maioria dos cabeçalhos de C sem problemas. Caso se receba avisos (warnings) na varredura que pareça ser um caso especial, pode-se informar ao GTK-Doc para ignorá-los. Bloco de comentário do GTK-Doc #ifndef __GTK_DOC_IGNORE__ /* código não analisável aqui */ #endif Limitações Note que o GTK-Doc oferece suporte a #ifndef(__GTK_DOC_IGNORE__), mas não a #if !defined(__GTK_DOC_IGNORE__) ou outras combinações. Comentários de documentação Um comentário multilinha que comece com um “*” adicional marca um bloco de documentação que será processado pelas ferramentas do GTK-Doc. Bloco de comentário do GTK-Doc /** * identificador: * documentação ... */ O “identificador” é uma linha com o nome do item ao qual o comentário está relacionado. A sintaxe difere um pouco dependendo do item. O bloco “documentação” também é diferente para cada tipo de símbolo. Tipos de símbolos que levam parâmetros, como funções e macros, têm a descrição de parâmetro começando com uma linha vazia (apenas com um “*”). Posteriormente, segue com a descrição detalhada. Todas as linhas (fora das listagens do programa e seções CDATA) contendo apenas um “ *” (espaço em branco e asterisco) são convertidas para quebras de parágrafos. Se você não quiser uma quebra de parágrafo, altere isso para “ * “ (espaço, asterisco, espaço e espaço). Isso é útil em textos pré-formatados (listagens de código). Ao documentar um código, descreva dois aspectos: O que é: O nome de uma classe ou função pode, em alguns casos, levar a um entendimento equivocado pessoas com experiências diferentes. O que ele faz: Fale sobre usos comuns. Coloque em relação com a outra API. Uma vantagem do hipertexto de texto simples é a habilidade de ter links no documento. Porém, escrever a marcação correta para cada link pode ser entediante. GTK-Doc vem para ajudar fornecendo abreviações úteis. Use function() para se referir às funções ou macros que levam argumentos. Use @param para se referir a parâmetros. Também, use isso ao se referir a parâmetros de outras funções, relacionadas àquele sendo descrito. Use %constant para se referir a uma constante, ex.: %G_TRAVERSE_LEAFS. Use #symbol para se referir a outros tipos de símbolos, ex.: structs, enums e macros que não levam argumentos. Use #Object::signal para se referir a um sinal de GObject. Use #Object:property para se referir a uma propriedade de GObject. Use #Struct.field para se referir a um campo dentro de uma estrutura e #GObjectClass.foo_bar() para se referir a um vmethod. Se você precisar usar os caracteres especiais “<”, “>”, “()”, “@”, “%” ou “#” em sua documentação sem GTK-Doc alterando-os, você pode usar as entidades XML “&lt;”, “&gt;”, “&lpar;”, “&rpar;”, “&commat;”, “&percnt;” e “&num;”, respectivamente, ou escapá-los com uma contrabarra “\”. DocBook pode fazer mais do que apenas links. Ele também pode ter listas, exemplos, títulos e imagens. A partir da versão 1.20, a forma preferível é usar um subconjunto de sintaxe de formatação de texto básica chamada Markdown. Em versões mais antigas do GTK-Doc, qualquer documentação que inclui Markdown será renderizada como está. Por exemplo, itens de lista aparecerão como linhas começando com um traço. Enquanto markdown é agora preferível, é possível misturar ambos. Uma limitação aqui é que é possível usar docbook xml no markdown, mas não há suporte a markdown no docbook xml. Em versões mais antigas do GTK-Doc, se você precisasse de suporte para formatação adicional, você precisaria de habilitar o uso de tags de XML de docbook dentro de comentários de documentação colocando (ou ) na variável MKDB_OPTIONS dentro de Makefile.am. Bloco de comentário do GTK-Doc usando Markdown /** * identificador: * * parágrafo de documentação ... * * # Subtítulo # * * ## Segundo subtítulo * * # Subtítulo com um link âncora # {#titulo-dois} * * mais documentação: * * - item 1 da lista * * Parágrafo dentro de um item de lista. * * - item 2 da lista * * 1. item numerado da lista * * 2. outro item numerado da lista * * Outro parágrafo. [Um link para o site do GNOME](http://www.gnome.org/) * * ![uma imagem embutida](plot-result.png) * * [Um link para um título acima][titulo-dois] * * Um exemplo em linguagem C: * |[<!-- language="C" --> * GtkWidget *label = gtk_label_new ("Esplêndido!"); * ]| */ Mais exemplos de quais tags de markdown tags há suporte podem ser encontrados na Referência de sintaxe de markdown de documentação GTK. Como já mencionado anteriormente, GTK-Doc serve para documentar API pública. Portanto, não é possível escrever documentação para símbolos estáticos. Não obstante, é bom comentar estes símbolos também. Isso ajuda outros desenvolvedores a entender seu código. Portanto, é recomendado comentá-los usando comentários normais (sem o segundo “*” na primeira linha). Se, posteriormente, a função precisar ser publicada, tudo que precisa ser feito é adicionar outro “*” no bloco de comentário e inserir o nome do símbolo no lugar correto do arquivo e seções. Documentando seções Cada seção da documentação contém informações sobre uma classe ou um módulo. Para introduzir o componente, pode-se escrever um bloco de seção. A descrição curta também é usada dentro da tabela de conteúdo (sumário). Todos os @fields são opcionais. Bloco de comentário de sessão /** * SECTION:meepapp * @short_description: A classe do aplicativo * @title: Aplicativo Meep * @section_id: * @see_also: #MeepSettings * @stability: Estável * @include: meep/app.h * @image: aplicativo.png * * A classe do aplicativo cuida de ... */ SECTION:<nome> O nome vincula a documentação da seção à respectiva parte do arquivo <pacote>-sections.txt. O nome informado aqui deve corresponder à tag <FILE> no arquivo <pacote>-sections.txt. @short_description Uma descrição de uma linha da sessão,que mais tarde aparecerá após os links no TOC (sumário) no topo da página da sessão. @title O padrão para título de seção é <nome> da declaração da SECTION. Ele pode ser sobrescrito com o campo @title. @section_id Sobrescreve o uso do título como um identificador de seção. Para GObjects, o <title> é usado como um section_id e para outras seções ele é <MÓDULO>-<title>. @see_also Uma lista de símbolos que estão relacionados a esta sessão. @stability Uma descrição informal do nível de estabilidade que esta API tem. Nós recomendamos o uso de um desses termos: Estável – A intenção de uma interface estável é permitir terceiros arbitrários desenvolverem aplicativos para essas interfaces, lançá-los e ter a confiança de que eles vão funcionar em todos os lançamentos menores do produto (após aquele no qual a interface foi introduzida e naquele mesmo lançamento maior). Atém mesmo em um lançamento maior, espera-se que alterações incompatíveis sejam raras e que tenham fortes justificativas. Instável – Interfaces instáveis são experimentais ou transicionais. Elas são normalmente usadas para dar a desenvolvedores externos um acesso prévio a nova tecnologia ou em rápida alteração, ou para fornecer uma solução interina para um problema que uma solução mais genérica foi antecipada. Nenhuma responsabilidade é assumida pela compatbilidade dos binários ou dos fontes de uma versão menor para a próxima. Privado – Uma interface que pode ser usada dentro da própria pilha do GNOME, mas que não está documentada para usuários finais. Tais funções deveriam ser usadas nas formas especificadas e documentadas. Interna – Uma interface que é interna a um módulo e não requer documentação para o usuário final. Funções que não estão documentadas são presumidas como sendo “Interna”. @include Os arquivos #include a ser mostrado na sinopse da seção (uma lista separada por vírgulas), sobrescrevendo o valor global do arquivo de seção ou linha de comando. Este item é opcional. @image A imagem a ser exibida no topo da página de referência desta seção. Isso frequentemente será um tipo de diagrama para ilustrar a aparência visual de uma classe ou uma diagrama de suas relações a outras classes. Este item é opcional. Para evitar recompilação desnecessária após alterações de documentação inseridas nas documentações de seção no fonte em C onde possível. Documentando símbolos Cada símbolo (função, macro, struct, enum, signal e property) é documentado em uma bloco separado. O bloco é melhor localizado perto da definição dos símbolos, de forma que seja fácil de mantê-los em sincronia. Portanto, as funções são normalmente documentadas no fonte em C e macros, scructs e enums no arquivo de header. Tags gerais Você pode adicionar informação sobre versionamento em todos os elementos de documentação para informar quando uma API foi introduzida ou quando ela se tornou obsoleta. Tags de versionamento Since: Descrição de desde qual versão do código a API está disponível. Deprecated: Parágrafo denotando que esta função deveria não mais ser usada. A descrição deveria apontar o leitor para a nova API. Você também pode adicionar informação sobre estabilidade em todos os elementos de documentação para indicar se a estabilidade de uma API é garantida para eles para futuros lançamentos menores do projeto. O nível de estabilidade padrão para todos os elementos de documentação pode ser definido passando o argumento para gtkdoc-mkdb com um dos valores abaixo. Tags de estabilidade Stability: Stable Marca o elemento como estável. Isto é para APIs públicas cuja estabilidade é garantida para todos os próximos lançamentos menores do projeto. Stability: Unstable Marca o elemento como instável. Isto é para APIs públicas que são publicados como versão de desenvolvimento antes de se tornar estável. Stability: Private Marca o elemento como privado. Isto é para interfaces que podem ser usadas por um conjunto pequeno de módulos, mas não por terceiros. Tags gerais /** * foo_get_bar: * @foo: Um foo * * Obtém o bar do @foo. * * Returns: bar do @foo * * Since: 2.6 * Deprecated: 2.12: Use foo_baz_get_bar() no seu lugar. */ Bar * foo_get_bar(Foo *foo) { ... Anotações Os blocos de documentação podem conter etiquetas de anotação. Essas etiquetas serão renderizadas com dicas descrevendo seu significado. As etiquetas são usadas pelo GObject Introspection para gerar ligações de linguagem. Uma lista detalhada das etiquetas suportadas pode ser encontrada na documentação do GObject Introspection . Anotações /** * foo_get_bar: (anotação) * @foo: (anotação): algum foo * * Obtém bar do @foo. * * Returns: (anotação): bar do @foo */ ... /** * foo_set_bar_using_the_frobnicator: (anotação) (outra anotação) * (e uma outra anotação) * @foo: (anotação) (uma outra anotação): algum foo * * Define bar no @foo. */ Bloco de comentário de função Por favor, lembre-se de: Documente se objetos, listas, strings, etc. retornados devem ser não usados/não referenciados/liberada. Documente se parâmetros pode ser NULL e o que acontece se eles o forem. Mencione pré-condições e pós-condições interessantes onde for apropriado. Gtk-doc presume que todos os símbolos (macros, funções) começando com “_” são privados. Eles são tratados como funções estáticas. Bloco de comentário de função /** * nome_da_função: * @par1: descrição do parâmetro 1. Esta pode se estender por mais de * uma linha. * @par2: descrição do parâmetro 2 * @...: uma lista de bars terminada em %NULL * * A descrição da função vai aqui. Você pode usar @par1 para se referir a parâmetros * de forma que eles ficam em destaque na saída. Você também pode usar %constant * para constantes, nome_da_função2() para funções e #GtkWidget para links para * outras declarações (que pode ser documentada em outro lugar). * * Returns: um inteiro. * * Since: 2.2 * Deprecated: 2.18: Use outra_função() em seu lugar. */ Tags de função Returns: Parágrafo descrevendo o resultado retornado. @...: No caso da função possuir argumentos variados, você deveria usar esta tag (@Varargs: também funciona por motivos de histórico). Bloco de comentário de propriedade Bloco de comentário de propriedade /** * AlgumWidget:alguma-propriedade: * * Aqui você pode documentar uma propriedade. */ g_object_propriedade_install_classe (object_classe, PROP_ALGUMA_PROPRIEDADE, ...); Bloco de comentário de sinal Por favor, lembre-se de: Documente quando o sinal é emitido e se ele é emitido antes ou após outros sinais. Documente o que um aplicativo pode fazer no manipulador do sinal. Bloco de comentário de sinal /** * FooWidget::foobarizado: * @widget: o widget que recebeu o sinal * @foo: algum foo * @bar: algum bar * * O sinal ::foobarized é emitido cada vez que alguém tenta foobarizar @widget. */ foo_sinais[FOOBARIZADO] = g_signal_novo ("foobarizado", ... Bloco de comentário de struct Bloco de comentário de struct /** * FooWidget: * @bar: algum #gboolean * * Este é o melhor widget, já mais visto. */ typedef struct _FooWidget { GtkWidget parent_intance; gboolean bar; } FooWidget; Use /*< private >*/ antes dos campos da struct privada que você deseja esconder. Use /*< public >*/ para o comportamento inverso. Se o primeiro campo for “g_iface”, “parent_instance” ou “parent_class”, ele será automaticamente considerado como privado e não precisará ser mencionado no bloco de comentário. Blocos de comentário de struct também podem ser usados para GObjects e GObjectClasses. É normalmente uma boa ideia adicionar um bloco de comentário para uma classe, se ela possui vmethods (pois assim é como elas podem ser documentadas). Para o próprio GOBject pode-se usar os documentos de seção relacionados, tendo um bloco separado para a instância do struct seria útil se a instância possui campos públicos. Uma desvantagem aqui é que isso cria duas entradas no índice do mesmo nome (a estrutura e a seção). Bloco de comentário de enum Bloco de comentário de enum /** * Alguma coisa: * @ALGUMACOISA_FOO: alguma coisa foo * @ALGUMCAOISA_BAR: alguma coisa bar * * Valores de enum usados para a coisa, para especificar a coisa. */ typedef enum { ALGUMACOISA_FOO, ALGUMACOISA_BAR, /*< private >*/ ALGUMACOISA_CONTAGEM } Alguma coisa; Use /*< private >*/ antes de valores privados de enum que você deseja ocultar. Use /*< public >*/ para o comportamento inverso. Documentação de programa em-linha Você pode documentar programas e sua interface de linha de comando usando documentação em-linha. Tags PROGRAM Define o início da documentação de um programa. @short_description: Define uma descrição breve do programa. (Opcional) @synopsis: Define os argumentos, ou lista de argumentos, que o programa pode receber. (Opcional) @see_also: A seção “See Also” (Veja Também) de páginas de manual. (Opcional) @arg: Argumento(s) passado(s) para o programa e sua descrição. (Opcional) Description: Um descrição mais longa do programa. Returns: Especifique qual(is) valor(es) o programa retorna. (Opcional) Exemplo de documentação de programa. Bloco de documentação de programa /** * PROGRAM:programa-teste * @short_description: Um programa teste * @synopsis: programa-teste [*OPÇÕES*...] --arg1 *arg* *ARQUIVO* * @see_also: teste(1) * @--arg1 *arg*: define arg1 para *arg* * @--arg2 *arg*: define arg2 para *arg* * @-v, --version: Exibe o número da versão * @-h, --help: Exibe a mensagem de ajuda * * Descrição longa do programa. * * Returns: Zero no caso de sucesso, não-zero no caso de falha */ int main(int argc, char *argv[]) { return 0; } Tags úteis do DocBook Aqui estão algumas tags de DocBook que são muito úteis quando se está documentado o código. Para vincular a outra seção nas documentações do GTK: <link linkend="glib-Hash-Tables">Tabela de hashes</link> O "linked" é a identificação SGML/XML no item superior da página a qual você deseja vincular. Para a maioria das páginas isto é atualmente a parte (“gtk”, “gdk”, “glib”) e, então, o título da página (“Hash Tables”). Para os widgets isso é apenas o nome da classe. Espaços e sublinhados são convertidos em '-' para estar em conformidade com SGML/XML. Para se referir a uma função externa, como, por exemplo, uma função padrão do C: <function>...</function> Para incluir um código de exemplo: <example> <title>Usando uma GHashTable.</title> <programlisting language="C"> ... </programlisting> </example> ou possivelmente este, para fragmentos de código bem curtos que não precisam de um título: <informalexample> <programlisting language="C"> ... </programlisting> </informalexample> . Nos dois casos, o atributo language é opcional e é usado como uma dica para o mecanismo de destaque de sintaxe (pigmentos para saída html). Para este último, GTK-Doc também possui suporte a uma abreviação: |[ ... ]| Para incluir listas com marcadores: <itemizedlist> <listitem> <para> ... </para> </listitem> <listitem> <para> ... </para> </listitem> </itemizedlist> Para incluir uma nota que fique fora do texto: <note> <para> Certifique-se de que você liberou os dados após usá-los. </para> </note> Para se referir a um tipo: <type>unsigned char</type> Para se referir a uma estrutura externa (não uma descrita nos documentos do GTK): <structname>XFontStruct</structname> Para se referir a um campo de uma estrutura: <structfield>len</structfield> Para se referir a um nome de classe, nós possivelmente poderíamos usar: <classname>GtkWidget</classname> mas você provavelmente vai estar usando #GtkWidget em vez disso (para criar automaticamente um link para a página do GtkWidget – veja as abreviações). Para enfatizar um texto: <emphasis>Isso é importante</emphasis> Para nome de arquivos use: <filename>/home/usuario/documentos</filename> Para se referir a chaves use: <keycombo><keycap>Control</keycap><keycap>L</keycap></keycombo> Preenchendo os arquivos extras Há alguns poucos arquivos extras, que precisam ser mantidos junto com os comentários inseridos no código-fonte: <pacote>.types, <pacote>-docs.xml (no passado, .sgml), <pacote>-sections.txt. Editando o arquivo de tipos Se sua biblioteca ou aplicativo inclui GObjects, você deseja que seus sinais, argumentos/parâmetros e posição na hierarquia sejam mostrados na documentação. Tudo que você precisa fazer é listar as funções xxx_get_type junto com seus include dentro do arquivo <pacote>.types. Exemplo de arquivo <pacote>.types #include <gtk/gtk.h> gtk_accel_label_get_type gtk_adjustment_get_type gtk_alignment_get_type gtk_arrow_get_type Desde o GTK-Doc 1.8, o gtkdoc-scan pode gerar esta lista para você. Basta adicionar “--rebuild-types” a SCAN_OPTIONS no Makefile.am. Se você usar esta abordagem, você não deveria distribuir o arquivo de tipos nem tê-lo sob um controle de versão. Editando o documento mestre O Gtk-Doc produz documentação em DocBook SGML/XML. Ao processar os comentários inseridos nos fontes, as ferramentas do GTK-Doc geram uma página de documentação por classe ou módulo como um arquivo separado. O documento mestre os inclui e os coloca em uma ordem. Enquanto o Gtk-Doc cria um modelo de documento mestre para você, execuções posteriores não vão tocá-lo novamente. Isso significa que se pode estruturar a documentação livremente. Isso inclui agrupamento de páginas e adição de páginas extras. O Gtk-Doc agora possui uma suíte de teste, na qual também o documento mestre é recriado do zero. É uma boa ideia verificar isso de tempo em tempo para ver se há itens a serem introduzidos lá. Não crie tutoriais como documentos extras. Apenas escreva capítulos extras. O benefício de embutir diretamente o tutorial para sua biblioteca na documentação da API é que é mais fácil vincular o tutorial a um símbolo da documentação. Além disso, as chances são mais altas que o tutorial obtenha atualizações junto com a biblioteca. Então, quais são as coisas para se alterar dentro do documento mestre? Para começar é apenas um pouco. Existem alguns mantedores de espaço (texto em colchetes) que você deve cuidar. Cabeçalho do documento mestre <bookinfo> <title>Manual de referência do NOMEDOMÓDULO</title> <releaseinfo> for NOMEDOMÓDULO [VERSÃO] A última versão desta documentação também pode ser encontrada on-line em <ulink role="online-location" url="http://[SERVIDOR]/NOMEDOMÓDULO/index.html">http://[SERVIDOR]/NOMEDOMÓDULO/</ulink>. </releaseinfo> </bookinfo> <chapter> <title>[Insira o título aqui]</title> Além disso, alguns elementos de opção são criados na forma comentada. Você pode revisá-los e habilitá-los como preferir. Parte opcional do documento mestre <!-- habilite isso se você usa anotações do gobject introspection <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include> --> Finalmente você precisa adicionar nova seção sempre que você a introduzir. A ferramenta gtkdoc-check vai lembrar você de arquivos xml recentemente gerados que ainda não foram incluídos na documentação. Incluindo seções geradas <chapter> <title>minha biblioteca</title> <xi:include href="xml/object.xml"/> ... Editando o arquivo de seção O arquivo de seção é usado para organizar a saída da documentação pelo GTK-Doc. Aqui pode-se especificar qual símbolo pertence a qual módulo ou classe e controla a visibilidade (pública ou privada). O arquivo de seção é uma arquivo texto simples com seções delimitadas por tags. Linhas em branco são ignoradas e linhas começando com um “#” são tratadas como linhas de comentários. Enquanto as tags fazem o arquivo se parecer xml, ele não é. Por favor, não feche tags como <SUBSECTION>. Incluindo seções geradas <INCLUDE>libmeep/meep.h</INCLUDE> <SECTION> <FILE>meepapp</FILE> <TITLE>MeepApp</TITLE> MeepApp <SUBSECTION Standard> MEEP_APP ... MeepAppClass meep_app_get_type </SECTION> A tag <FILE> ... </FILE> é usada para especificar o nome de arquivo, sem qualquer sufixo. Por exemplo, ao usar “<FILE>gnome-config</FILE>” resultará nas declarações da seção serem retornadas no arquivo modelo tmpl/gnome-config.sgml, o qual será convertido no arquivo DocBook XML xml/gnome-config.sgml ou no arquivo DocBook XML xml/gnome-config.xml. (O nome do arquivo HTML é baseado no nome do módulo e no título da seção ou, para GObjects, é baseado no nome da classe GObjects convertidos os caracteres para minúsculos). A tag <TITLE> ... </TITLE> é usada para especificar o título da seção. Ela é usada apenas antes do modelo (se usado) ser criado inicialmente, já que o título definido no arquivo de modelo sobrescreve este. Também, se for usado o comentário SECTION nos fontes, isso está obsoleto. Você pode agrupar itens na seção usando a tag <SUBSECTION>. Atualmente, ela retorna uma linha em branco entre as subseções na seção de sinopse. Você também pode usar <SUBSECTION Standard> para declarações padrão do GObject (ex.: as funções como g_object_get_type e macros como G_OBJECT(), G_IS_OBJECT() etc.). Atualmente, estas são deixadas fora da documentação. Você também pode usar <SUBSECTION Private> para declarações privadas que não serão retornadas (é uma forma prática de evitar mensagens de aviso sobre declarações não usadas). Se sua biblioteca contém tipos privados que você não deseja que apareçam na hierarquia do objeto e a linha de classes implementadas ou exigidas, adicione-as a uma subseção privada. Se você colocaria o GObject e GObjectClass como structs numa seção padrão ou pública depende se há entradas públicas (variáveis, vmethods). Você também pode usar <INCLUDE> ... </INCLUDE> para especificar os arquivos #include que são mostrados nas seções de sinopse. Ela contém uma lista separada por vírgula de arquivos #include, sem os sinais de maior que e menor que. Se você define-a fora de quaisquer seções, ela age para todas as seções até o fim do arquivo. Se você define-a em uma seção, ela só vai se aplicar àquela seção. Controlando o resultado Uma execução do GTK-Doc gera arquivos de relatórios dentro do diretório de documentação. Os arquivos gerados são chamados: <pacote>-undocumented.txt, <pacote>-undeclared.txt e <pacote>-unused.txt. Todos eles são arquivos texto simples que podem ser facilmente visualizados e pós-processados. O arquivo <pacote>-undocumented.txt começa com um sumário de cobertura da documentação. Abaixo estão duas seções divididas por linhas brancas. A primeira seção lista símbolos não documentados e incompletos. A segunda seção faz o mesmo para os documentos de seção. Entradas incompletas são aquelas que foram documentadas, mas nas quais, por exemplo, um novo parâmetro foi adicionado. O arquivo <pacote>-undeclared.txt lista símbolos dados no <pacote>-sections.txt, mas não encontrados nos fontes. Verifique se eles foram removidos ou se eles foram escritos incorretamente. O arquivo <pacote>-unused.txt lista nomes de símbolo cuja documentação foi localizada na varredura do GTK-Doc, mas que não sabe onde colocá-los. Isso significa que o símbolo não foi adicionado ainda ao arquivo <pacote>-sections.txt. Habilite ou adicione a linha no Makefile.am. Se pelo menos GTK-Doc 1.9 estiver instalado, isso vai executar verificações de sanidade durante a execução de make check. Também pode-se buscar nos arquivos produzidos pela varredura do código-fonte: <pacote>-decl-list.txt e <pacote>-decl.txt. O primeiro pode ser comparado com o arquivo de seção, se ele for mantido manualmente. O segundo lista todas as declarações de cabeçalhos. Se um símbolo está faltando, pode-se verificar se este arquivo o contém. Se o projeto é baseado em GObject, pode-se também procurar nos arquivos produzidos pela varredura de objetos: <pacote>.args.txt, <pacote>.hierarchy.txt, <pacote>.interfaces.txt, <pacote>.prerequisites.txt e <pacote>.signals.txt. Se há símbolos faltando em qualquer um deles, pode-se exigir que o GTK-Doc mantenha o arquivo intermediário de varredura para análise posterior, executando GTK_DOC_KEEP_INTERMEDIATE=1 make. Modernizando a documentação GTK-Doc está por aí já faz um tempo. Nesta seção, nós listamos novas funcionalidades juntamente da versão desde a qual está disponível. GTK-Doc 1.9 Ao usar xml em vez de sgml, na verdade, é possível nomear o documento mestre <pacote>-docs.xml. Essa versão provê suporte em Makefile.am. Quando esta opção está habilitada, o <package>-sections.txt é auto-gerado e pode ser removido a partir do VCS. Isso só funciona corretamente para projetos que têm uma estrutura muito regular (ex.: cada par .{c,h} vai criar uma nova seção). Se uma pessoa organiza um projeto próximo a isso atualizando um arquivo de seção mantido manualmente pode ser tão simples quanto executando meld <package>-decl-list.txt <package>-sections.txt. A versão 1.8 já introduziu a sintaxe para documentação seções nos fontes em vez dos arquivos separados sob tmpl. Essa versão adiciona opções para alternar todo o módulo de documentação para não usar a etapa de compilação extra do tmpl, usando no configure.ac. Se você não possui um tmpl no seu sistema de controle de versão e ainda não trocou, basta adicionar uma opção ao configure.ac e está resolvido. GTK-Doc 1.10 Essa versão provê suporte no Makefile.am. Quando isso está habilitado, o <package>.types é auto-gerado e pode ser removido do VCS. Quando usando essa funcionalidade é importante também configurar o IGNORE_HFILES no Makefile.am para código que é compilado condicionalmente. GTK-Doc 1.16 Essa versão inclui uma nova ferramenta chamada gtkdoc-check. Essa ferramenta pode executar um conjunto de verificações de sanidade na sua documentação. Ela é habilitada adicionando essas linhas ao final do Makefile.am. Habilitar gtkdoc-check if ENABLE_GTK_DOC TESTS_ENVIRONMENT = \ DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir) TESTS = $(GTKDOC_CHECK) endif GTK-Doc 1.20 A versão 1.18 trouxe algum suporte inicial a markdown. O uso de markdown em comentários de documentação é menos intrusiva do que escrever xml de docbook. Essa versão melhora em muito nisso e adiciona muito mais estilos. A seção que explica a sintaxe de comentário tem todos os detalhes. GTK-Doc 1.25 Os makefiles fornecidos com esta versão geram um arquivo de entidade em xml/gtkdocentities.ent, contendo entidades para, por exemplo, nome-pacote e versão-pacote. Você pode usar isto, por exemplo, no arquivo xml principal para evitar ter que inserir diretamente o número de versão. Logo abaixo encontra-se um exemplo que mostra como o arquivo de entidade é incluído no modelo mestre e como as entidades são usadas. As entidades também podem ser usadas em todos arquivos gerados, GTK-Doc usará o mesmo cabeçalho xml nos arquivos xml gerados. Usando entradas geradas previamente <?xml version="1.0"?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'"> <!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent"> %gtkdocentities; ]> <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude"> <bookinfo> <title>Manual de referência do &nome-pacote;</title> <releaseinfo> para &versão-pacote;. A última versão desta documentação pode ser encontra on-line em <ulink role="online-location" url="http://[SERVIDOR]/&nome-pacote;/index.html">http://[SERVIDOR]/&nome-pacote;/</ulink>. </releaseinfo> </bookinfo> Documentando outras interfaces Até agora nós temos usado o GTK-Doc para documentar a API de um código. As próximas sessões contêm sugestões de como as ferramentas podem ser usadas para documentar outras interfaces, também. Opções de linha de comando e de páginas man Já que também é possível gerar páginas man para um refentry do docbook, soa como uma boa ideia usá-lo para este propósito. Desta forma, a interface é parte da referência e é possível obter a página man livremente. Documentar a ferramenta Crie um arquivo refentry por ferramenta. Segundo nosso exemplo nós chamaríamos ele de meep/docs/reference/meeper/meep.xml. Para as tags xml que devem ser usadas e podem parecer no arquivo gerado no subdiretório xml assim como exemplos, por exemplo, em glib. Adicionando a verificação extra ao configure Verificações extra no configure AC_ARG_ENABLE(man, [AC_HELP_STRING([--enable-man], [regenerate man pages from Docbook [default=no]])],enable_man=yes, enable_man=no) AC_PATH_PROG([XSLTPROC], [xsltproc]) AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno) Adicionando as regras extras ao makefile Verificações extra no configure man_MANS = \ meeper.1 if ENABLE_GTK_DOC if ENABLE_MAN %.1 : %.xml @XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $< endif endif BUILT_EXTRA_DIST = $(man_MANS) EXTRA_DIST += meep.xml Interfaces DBus (CORRIJA-ME: http://hal.freedesktop.org/docs/DeviceKit/DeviceKit.html, http://cgit.freedesktop.org/DeviceKit/DeviceKit/tree/doc/dbus) Perguntas frequentes Questão Resposta Sem hierarquia de classe. A função de objetos xxx_get_type() não foi inserida no arquivo <pacote>.types. Ainda sem hierarquia. Nomenclatura faltando ou incorreta no arquivo <pacote>-sections.txt (veja a explicação). Droga. Eu ainda não tenho hierarquia de classes. Por acaso o nome do objeto (nome da struct da instância, ex. GtkWidget) faz parte da seção normal (não coloque isso em subseções Standard ou Private). Nenhum símbolo de índice. O <pacote>-docs.{xml,sgml} contém um índice que “xi:inclui” o índice gerado? Símbolos não estão vinculados ao seus doc-section. O doc-comment está usando a marcação correta (adicionado #,% or ())? Verifique se o gtkdoc-fixxref avisa sobre xrefs não resolvidos. Uma nova classe não aparece nos documentos. A nova página foi “xi:incluída” do <pacote>-docs.{xml,sgml}. Um novo símbolo não aparece nos documentos. O doc-comment está formatado adequadamente? Verifique erros de escrita no começo do comentário. Verifique se o gtkdoc-fixxref avisa sobre xrefs não resolvíveis. Verifique se o símbolo está listado corretamente no <pacote>-sections.txt em uma subseção pública. Um tipo está faltando da hierarquia de classe. Se o tipo está listado no <pacote>.hierarchy, mas não em xml/tree_index.sgml, então certifique-se de que o tipo está colocado corretamente no <pacote>-sections.txt. Se a instância do tipo (ex.: GtkWidget) não está listada ou incidentalmente marcada como privada, ela não será mostrada. Obtenho links de seguimento de documentos para todas as anotações gobject. Verifique se xml/annotation-glossary.xml está “xi:incluído” de <pacote>-docs.{xml,sgml}. Parâmetro descrito no bloco de comentário do código-fonte não existe Verifique se o protótipo no cabeçalho tem nomes de parâmetros diferentes da fonte. múltiplos “IDs” para restrições do fim do link XYZ O símbolo XYZ aparece duas vezes no arquivo <pacote>-sections.txt. Elemento typename no espaço de nome '' encontrado em para, mas nenhum modelo correspondeu. Ferramentas relacionadas ao gtk-doc GtkDocPlugin – um plug-in de integração com Trac GTK-Doc, que adiciona documentos de API a um site trac e integra com a pesquisa do trac. Gtkdoc-depscan – uma ferramenta (parte do gtk-doc) para verificar APIs usadas, a partir de suas tags, para determinar a versão mínima necessária. Versão 1.1, Março de 2000 2000Free Software Foundation, Inc.
Free Software Foundation, Inc. 51 Franklin Street, Suite 330, Boston, MA 02110-1301 USA
É permitido a qualquer um copiar e distribuir cópias exatas deste documento de licença, embora não seja permitido alterá-lo. Licença de Documentação Livre GNU 0. PREÂMBULO The purpose of this License is to make a manual, textbook, or other written document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of copyleft, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. Criamos esta Licença para usá-la para manuais para software livre, porque software livre precisa de documentação livre: um programa livre deve ser fornecido com manuais que proporcionam as mesmas liberdades que o software. Mas esta Licença não está limitada aos manuais de software; pode ser usada para qualquer trabalho textual, independentemente do assunto ou dele ser publicado como um livro impresso. Recomendamos esta Licença principalmente para trabalhos cujo propósito seja instrução ou referência. 1. APLICABILIDADE E DEFINIÇÕES This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The Document, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as you. A Modified Version of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A Secondary Section is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The Invariant Sections are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. The Cover Texts are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Transparent copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not Transparent is called Opaque. Exemplos de formatos adequados para cópias Transparentes incluem ASCII simples sem marcação, formato de entrada Texinfo, formato de entrada LaTeX, SGML ou XML usando DTD publicamente disponível e HTML simples, conforme padrão, projetados para modificação humana. Os formatos Opacos incluem PostScript, PDF, formatos proprietários que podem ser lidos e editados apenas por processadores de texto proprietários, SGML ou XML para os quais o DTD e/ou ferramentas de processamento não estão geralmente disponíveis e o HTML gerado por máquina produzido por alguns processadores de texto para apenas para fins de saída. The Title Page means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, Title Page means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. 2. CÓPIA LITERAL You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. Você também pode emprestar cópias, nas mesmas condições acima mencionadas, e você pode publicar cópias. 3. COPIANDO EM QUANTIDADE If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. Se os textos necessários para qualquer uma das coberturas forem demasiado volumosos para se ajustar de forma legível, você deve colocar os primeiros listados (tanto quanto encaixar razoavelmente) na capa real e continuar o resto em páginas adjacentes. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. 4. MODIFICAÇÕES You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: A Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. B List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five). C State on the Title Page the name of the publisher of the Modified Version, as the publisher. D Preserve all the copyright notices of the Document. E Adicionar um aviso de direitos autorais apropriado para suas modificações adjacentes aos outros avisos de direitos autorais. F Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. G Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice. H Incluir uma cópia inalterada desta Licença. I Preserve the section entitled History, and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled History in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. J Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the History section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. K In any section entitled Acknowledgements or Dedications, preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. L Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. M Delete any section entitled Endorsements. Such a section may not be included in the Modified Version. N Do not retitle any existing section as Endorsements or to conflict in title with any Invariant Section. If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. You may add a section entitled Endorsements, provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version . 5. COMBINANDO DOCUMENTOS You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections entitled History in the various original documents, forming one section entitled History; likewise combine any sections entitled Acknowledgements, and any sections entitled Dedications. You must delete all sections entitled Endorsements. 6. COLEÇÕES DE DOCUMENTOS You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. Você pode extrair um único documento de tal coleção e distribuí-lo individualmente sob esta Licença, desde que você insira uma cópia desta Licença no documento extraído e siga esta Licença em todos os outros aspectos referentes à cópia literal desse documento. 7. AGREGAÇÃO COM TRABALHOS INDEPENDENTES A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an aggregate, and this License does not apply to the other self-contained works thus compiled with the Document , on account of their being thus compiled, if they are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate. 8. TRADUÇÃO Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail. 9. TERMINAÇÃO You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 10. FUTURAS REVISÕES DESTA LICENÇA The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/. Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License or any later version applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. Adendo Para usar esta Licença em um documento que você escreveu, inclua uma cópia da Licença no documento e coloque os seguintes avisos de direitos autorais e de licenças logo após a página de título:
Copyright ANO SEU NOME. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license is included in the section entitled GNU Free Documentation License.
If you have no Invariant Sections, write with no Invariant Sections instead of saying which ones are invariant. If you have no Front-Cover Texts, write no Front-Cover Texts instead of Front-Cover Texts being LIST; likewise for Back-Cover Texts. If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.