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 can do more than just links. One can also have lists, examples, headings, and images. As of version 1.20, the preferred way is to use a subset of the basic text formatting syntax called Markdown. On older GTK-Doc versions any documentation that includes Markdown will be rendered as is. For example, list items will appear as lines starting with a dash.

In older GTK-Doc releases, if you need support for additional formatting, you would need to enable the usage of docbook SGML/XML tags inside doc-comments by putting --xml-mode or --sgml-mode in the variable MKDB_OPTIONS inside Makefile.am.

Example 3-3GTK-Doc comment block using Markdown
/**
 * identifier:
 *
 * documentation paragraph ...
 *
 * # Sub Heading #
 *
 * ## Second Sub Heading
 *
 * # Sub Heading With a Link Anchor # {#heading-two}
 *
 * more documentation:
 *
 * - list item 1
 *
 *   Paragraph inside a list item.
 *
 * - list item 2
 *
 * 1. numbered list item
 *
 * 2. another numbered list item
 *
 * Another paragraph. [A Link to the GNOME Website](http://www.gnome.org/)
 *
 * ![an inline image][plot-result.png]
 *
 * [A link to the heading anchor above][heading-two]
 *
 * A C-language example:
 * |[<!-- language="C" -->
 * GtkWidget *label = gtk_label_new ("Gorgeous!");
 * ]|
 */

          

More examples of what markdown tags are supported can be found in the GTK+ Documentation Markdown Syntax Reference.

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.