<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" xmlns:xi="http://www.w3.org/2003/XInclude" type="topic" id="documentation" xml:lang="pt-BR">

  <info>

    <link type="guide" xref="index#general-guidelines"/>

    <credit type="author copyright">

      <name>Federico Mena-Quintero</name>

      <email its:translate="no">federico@gnome.org</email>

      <years>2013</years>

    </credit>

    <credit type="author copyright">

      <name>Philip Withnall</name>

      <email its:translate="no">philip.withnall@collabora.co.uk</email>

      <years>2015</years>

    </credit>

    <credit type="author copyright">

      <name>A equipe do GTK+</name>

    </credit>

    <include xmlns="http://www.w3.org/2001/XInclude" href="cc-by-sa-3-0.xml"/>

    <desc>Adicionando documentação a bibliotecas e APIs</desc>

    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">

      <mal:name>Rafael Fontenelle</mal:name>

      <mal:email>rafaelff@gnome.org</mal:email>

      <mal:years>2017</mal:years>

    </mal:credit>

  </info>

  <title>Documentação</title>

  <synopsis>

    <title>Resumo</title>

    <list>

      <item>
Use gtk_doc com configurações atualizadas para documentação de API. (<link xref="#gtk-doc"/>)
</item>

      <item>
Use entidades XML para inclusão de símbolos externos à documentação. (<link xref="#build-system"/>)
</item>

      <item>
Use uma tabela de conteúdos consistente e padrão para toda documentação de API para manter a familiaridade. (<link xref="#standard-layout"/>)
</item>

      <item>
Use <cmd>gdbus-codegen</cmd> para gerar documentação de API do D-Bus para incluir na compilação de gtk-doc. (<link xref="#dbus-api"/>)
</item>

      <item>
Adicione anotações de introspecção a toda documentação de API. (<link xref="#introspection-annotations"/>)
</item>

      <item>
Adicione linhas Since para toda documentação de API. (<link xref="#symbol-versioning"/>)
</item>

      <item>
Habilite testes de gtk-doc. (<link xref="#keeping-up-to-date"/>)
</item>

    </list>

  </synopsis>

  <section id="gtk-doc">

    <title>gtk-doc</title>

    
O sistema de documentação preferido para bibliotecas do GNOME é o <link href="http://www.gtk.org/gtk-doc/">gtk-doc</link>, o qual extrai comentários em linha do código e permite que você compile um documento <link href="http://docbook.org/">DocBook</link> e coleção de páginas HTML. Esses podem ser lidos em <link href="https://wiki.gnome.org/Apps/Devhelp">Devhelp</link>. Muito da infraestrutura do GNOME é construído para lidar com documentação escrita usando gtk-doc.

  </section>

  <section id="build-system">

    <title>Sistema de compilação</title>

    
Para integrar gtk-doc a um sistema de compilação do projeto, siga as <link href="https://developer.gnome.org/gtk-doc-manual/stable/settingup.html.en"> instruções no manual do gtk-doc</link>. Note que enquanto o arquivo <file>sections.txt</file> é 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 <link href="https://developer.gnome.org/gtk-doc-manual/stable/settingup_vcs.html.en"> no controle de versão</link>.

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

    @PACKAGE_VERSION@

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

  </section>

  <section id="standard-layout">

    <title>Layout padrão</title>

    
Usar um layout padrão para a tabela de conteúdos, seções, apêndices etc. significa que o mesmo modelo de <file>nome-do-projeto-docs.xml</file> 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:

    <listing>

      <title><file>nome-do-projeto-docs.xml</file></title>

      <desc>Um arquivo de modelo de nível superior do gtk-doc para um projeto</desc>

      <xi:include href="example-docs.xml" parse="text"/>

    </listing>

  </section>

  <section id="licensing">

    <title>Licenciamento</title>

    
É 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 <link xref="#standard-layout">Layout padrão</link>, você deve incluir um <file>license.xml</file> no arquivo DocBook de nível superior do gtk-doc, o qual fornece o texto completo para sua licença de documentação.

  </section>

  <section id="public-api">

    <title>API pública</title>

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

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

  </section>

  <section id="introspection-annotations">

    <title>Anotações de introspecção</title>

    
Cada comentário gtk-doc deve ter as <link href="https://wiki.gnome.org/Projects/GObjectIntrospection/Annotations">anotações de introspeção de GObject</link> adequada. Essa são úteis por dois motivos:

    <list type="numbered">

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

      <item>
Elas permitem que APIs públicas sejam automaticamente vinculadas a outras linguagens, tais como Python ou JavaScript.
</item>

    </list>

    
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 <link xref="introspection">diretrizes de introspecção</link>.

  </section>

  <section id="symbol-versioning">

    <title>Versionamento de símbolo</title>

    
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 <file>configure.in</file> se<link xref="versioning#release-process">incrementação de versão pós-lançamento</link> 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 <file>*-docs.xml</file> 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>

  </section>

  <section id="dbus-api">

    <title>APIs de D-Bus</title>

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

    
Os arquivos DocBook podem ser incluídos no arquivo <file>*-docs.xml</file> 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 <file>Makefile.am</file> de gtk-doc, do contrário a compilação vai falhar. (Isso é para corrigir situações nas quais builddir não é igual a srcdir.)

  </section>

  <section id="keeping-up-to-date">

    <title>Mantendo a documentação atualizada</title>

      gtk-doc comes with support for checking the documentation with some basic

      tests. These check that all version indexes are included in the main

      <file>*-docs.xml</file> file and that all symbols are documented, among

      other things.

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

    TESTS = $(GTKDOC_CHECK)

    
Eles serão, então, executados como parte do <cmd>make check</cmd>.

  </section>

</page>