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.

Example 3-2Bloco 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 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 “&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 --xml-mode (ou --sgml-mode) na variável MKDB_OPTIONS dentro de Makefile.am.

Example 3-3Bloco 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 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.