Federico Mena-Quintero
federico@gnome.org 2013
Philip Withnall
philip.withnall@collabora.co.uk 2015
A equipe do GTK+
Adicionando documentação a bibliotecas e APIs
Rafael Fontenelle
rafaelff@gnome.org 2017

# Documentação

#

        Resumo

          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 gdbus-codegen para gerar documentação de API do D-Bus para incluir na compilação de gtk-doc. ()
          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. ()

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

# Sistema de compilação

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 sections.txt é gerado automaticamente na primeira vez que o gtk-doc é executado, ele não é gerado subsequentemente, e deve ser mantido atualizado. Ele também deve estar no controle de versão.

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 docs/version.xml.in, contendo:

@PACKAGE_VERSION@

Adicione-o a `AC_CONFIG_FILES` no configure.ac, então inclua-o ao arquivo central da documentação (*-docs.xml) usando: `<!ENTITY version SYSTEM "version.xml">` no `DOCTYPE` sobre o documento. A versão do pacote pode ser usada em linha como `&version;`.

# Layout padrão

Usar um layout padrão para a tabela de conteúdos, seções, apêndices etc. significa que o mesmo modelo de nome-do-projeto-docs.xml pode ser reusado com algumas alterações entre projetos. Ele também significa que o layout da documentação é similar por todos os projetos, fazendo dele mais familiar para os desenvolvedores.

O layout a seguir é sugerido:

## nome-do-projeto-docs.xml

Um arquivo de modelo de nível superior do gtk-doc para um projeto

# Licenciamento

É 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 license.xml no arquivo DocBook de nível superior do gtk-doc, o qual fornece o texto completo para sua licença de documentação.

# API pública

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 nomemodulo-sections.txt da documentação.

Para documentação adequadamente uma nova classe, ele precisa ser dado em sua própria seção no nomemodulo-sections.txt e a função `get_type()` para sua classe precisa ser listada em seu nomemodulo.types.

# Anotações de introspecção

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.

# Versionamento de símbolo

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 configure.in seincrementação de versão pós-lançamento estiver sendo usado.

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 *-docs.xml principal como um apêndice:

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

# APIs de D-Bus

Descrições de interface D-Bus contêm comentários de documentação, e podem ser extraídas do XML usando gdbus-codegen e transformadas em arquivos DocBook para serem incluídas pelo gtk-doc.

Os arquivos DocBook podem ser incluídos no arquivo *-docs.xml principal usando:

<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 Makefile.am de gtk-doc, do contrário a compilação vai falhar. (Isso é para corrigir situações nas quais `builddir` não é igual a `srcdir`.)

# Mantendo a documentação atualizada

gtk-doc comes with support for checking the documentation with some basic tests. These check that all version indexes are included in the main *-docs.xml file and that all symbols are documented, among other things.

Esses testes devem sempre estar habilitados, adicionando o seguinte para seu Makefile.am de gtk-doc:

TESTS = $(GTKDOC_CHECK)

Eles serão, então, executados como parte do make check.