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