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.

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