Use gtk_doc com configurações atualizadas para documentação de API. ()
Use entidades XML para inclusão de símbolos externos à documentação. ()
Use uma tabela de conteúdos consistente e padrão para toda documentação de API para manter a familiaridade. ()
Use
Adicione anotações de introspecção a toda documentação de API. ()
Adicione linhas Since para toda documentação de API. ()
Habilite testes de gtk-doc. ()
O sistema de documentação preferido para bibliotecas do GNOME é o gtk-doc, o qual extrai comentários em linha do código e permite que você compile um documento DocBook e coleção de páginas HTML. Esses podem ser lidos em Devhelp. Muito da infraestrutura do GNOME é construído para lidar com documentação escrita usando gtk-doc.
Para integrar gtk-doc a um sistema de compilação do projeto, siga as instruções no manual do gtk-doc. Note que enquanto o arquivo
A opção --flavour no-tmpl do gtk-doc deve ser usada, e o modo XML deve ser usado no lugar do SGML. (modo tmpl e SGML estão ambos desatualizados e são mais lentos que XML.)
Se a versão do pacote for necessária para ser substituída na documentação, crie um arquivo chamado
@PACKAGE_VERSION@
Adicione-o a AC_CONFIG_FILES no <!ENTITY version SYSTEM "version.xml"> no DOCTYPE sobre o documento. A versão do pacote pode ser usada em linha como &version;.
Usar um layout padrão para a tabela de conteúdos, seções, apêndices etc. significa que o mesmo modelo de
O layout a seguir é sugerido:
É importante tornar a licença usada para referências de API bem clara, especialmente se elas contiverem exemplos de código que poderia ser copiado.
Geralmente, projetos usam a mesma licença para sua referência de API que para o código do projeto em si, para evitar confusão. Alguns projetos usam CC-BY-SA 3.0 para toda documentação de referência. A escolha é sua.
Como mostrado no Layout padrão, você deve incluir um
Todas APIs públicas devem ter comentários de gtk-doc. Para funções, essas devem ser colocadas no arquivo fonte, diretamente sobre a função.
/**
* gtk_get_flow:
* @widget: a #GtkWidget
*
* Gets the flow of a widget.
*
* Note that flows may be laminar or turbulent...
*
* Returns: (transfer none): the flow of @widget
*/
GtkFlow *
gtk_get_flow (GtkWidget *widget)
{
...
}
Comentários de documentação para macros, tipos de função, structs de classe, etc. devem ser colocados próximo às definições, geralmente em arquivos de cabeçalhos.
Introduções de seção devem ser colocadas no arquivo fonte que elas descrevem, após o cabeçalho de licença:
/**
* SECTION:gtksizerequest
* @Short_Description: Height-for-width geometry management
* @Title: GtkSizeRequest
*
* The GtkSizeRequest interface is GTK+'s height-for-width (and
* width-for-height) geometry management system.
* ...
*/
Tenha em mente que para incluir uma função, macro, tipo de função ou tipo de struct, ele precisa ser listado no arquivo de
Para documentação adequadamente uma nova classe, ele precisa ser dado em sua própria seção no get_type() para sua classe precisa ser listada em seu
Cada comentário gtk-doc deve ter as anotações de introspeção de GObject adequada. Essa são úteis por dois motivos:
Elas adicionam informações importantes sobre tipos de parâmetros, anulabilidade e gerenciamento de memória para a documentação de API C gerada pelo gtk-doc.
Elas permitem que APIs públicas sejam automaticamente vinculadas a outras linguagens, tais como Python ou JavaScript.
Anotações de introspecção adicionam informações às APIs (funções, parâmetros de função, valor de retorno de função, estruturas, propriedades de GObject, sinais de GObject) nas quais, do contrário, não está presente na API C legível por máquina e existe apenas na forma de documentação legível por humano ou convenção. Elas são muito importantes.
Em comentários de gtk-doc, anotações devem ser preferidos a equivalentes legíveis por humanos, Por exemplo, ao documentar o parâmetro de uma função que pode ser NULL, use a anotação (nullable) e, vez de algum texto:
/**
* my_function:
* @parameter: (nullable): some parameter which affects something
*
* Body of the function documentation.
*/
Em vez de:
/**
* my_bad_function:
* @parameter: some parameter which affects something, or %NULL to ignore
*
* Bad body of the function documentation.
*/
Para mais informação sobre introspecção, veja as diretrizes de introspecção.
Quando um símbolo é adicionado à API pública, ele deve ter um comentário de documentação adicionado. Esse comentário deve sempre conter uma linha Since com o número da versão de pacote do lançamento que primeiro conterá a nova API. Isso deve ser o número que está no
Por exemplo:
/**
* my_function:
* @param: some parameter
*
* Body of the function documentation.
*
* Since: 0.5.0
*/
gtk-doc usa essa informação para gerar índices das APIs adicionadas em cada lançamento. Essas devem ser adicionadas ao
<part>
<title>Appendices</title>
<index id="api-index-full">
<title>API Index</title>
<xi:include href="xml/api-index-full.xml"><xi:fallback/></xi:include>
</index>
<index id="api-index-deprecated">
<title>Index of deprecated symbols</title>
<xi:include href="xml/api-index-deprecated.xml"><xi:fallback/></xi:include>
</index>
<index role="0.1.0">
<title>Index of new symbols in 0.1.0</title>
<xi:include href="xml/api-index-0.1.0.xml"><xi:fallback/></xi:include>
</index>
<!-- More versions here. -->
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
</part>
Descrições de interface D-Bus contêm comentários de documentação, e podem ser extraídas do XML usando
Os arquivos DocBook podem ser incluídos no arquivo
<chapter>
<title>C Interfaces</title>
<partintro>
<para>C wrappers for the D-Bus interfaces.</para>
</partintro>
<xi:include href="xml/SomeDBusService.xml"/>
<xi:include href="xml/SomeOtherService.xml"/>
</chapter>
Os arquivos XML gerados devem ser incluídos na variável content_files em seu builddir não é igual a srcdir.)
gtk-doc comes with support for checking the documentation with some basic
tests. These check that all version indexes are included in the main
Esses testes devem sempre estar habilitados, adicionando o seguinte para seu
TESTS = $(GTKDOC_CHECK)
Eles serão, então, executados como parte do