Comentários de documentação
Um comentário multilinha que começa com um “*” adicional marca um bloco de documentação que será processado pelas ferramentas 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 isso 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 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 “<”, “>”, “(”, “)”, “@”, “%” e “#”, 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 --xml-mode (ou --sgml-mode) na variável MKDB_OPTIONS dentro de Makefile.am.
/** * 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/) * *  * * [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 do quais tags de markdown tags tem suporte pode ser encontrado na Referência de sintaxe de markdown de documentação.
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 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.