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.

Localização da documentação
Antigamente, a maioria das documentações tinha que ser preenchida em arquivos residentes dentro do diretório tmpl. Isso tem as desvantagens das informações frequentemente não serem atualizadas e também que o arquivo tende a causar conflitos com sistemas de controle de versão.
Para evitar os problemas mencionados a seguir nós sugerimos que a documentação seja colocada dentro das fontes. Este manual vai apenas descrever esta forma de documentar código.
A varredura 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 arqui */
#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 começa 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 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.

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

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 --default-stability para gtkdoc-mkdb com um dos balores 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
Blocos de documentação podem conter tags de anotação. Essas tags serão renderizadas com dicas de ferramentas descrevendo seu significados. As tags são usadas pelo gobject-introspection para garantir associações (bindings) de linguagens. Uma lista detalhada tags aceitas podem ser encontrada no wiki.

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 privadas. Elas são tratadas 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::foobarized:
 * @widget: the widget that received the signal
 * @foo: some foo
 * @bar: some bar
 *
 * The ::foobarized signal is emitted each time someone tries to foobarize @widget.
 */
foo_signals[FOOBARIZED] =
  g_signal_new ("foobarized",
                ...

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 “Veja Também” (See Also) 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 quais 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 fim do link é o ID do 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>
      ...
  </programlisting>
</example>

ou possivelmente este, para fragmentos de código bem curtos que não precisam de um título:

<informalexample>
  <programlisting>
  ...
  </programlisting>
</informalexample>

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>