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.

While markdown is now preferred one can mix both. One limitation here is that one can use docbook xml within markdown, but markdown within docbook xml is not supported.

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 SGML/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.