Documentando símbolos
Cada símbolo (função, macro, struct, enum, signal e property) é documentado em uma bloco separado. O bloco é melhor localizado perto da definição dos símbolos, de forma que seja fácil de mantê-los em sincronia. Portanto, as funções são normalmente documentadas no fonte em C e macros, scructs e enums no arquivo de header.
- 3.3.1. Tags gerais
- 3.3.2. Anotações
- 3.3.3. Bloco de comentário de função
- 3.3.4. Bloco de comentário de propriedade
- 3.3.5. Bloco de comentário de sinal
- 3.3.6. Bloco de comentário de struct
- 3.3.7. Bloco de comentário de enum
3.3.1. Tags gerais
Você pode adicionar informação sobre versionamento em todos os elementos de documentação para informar quando uma API foi introduzida ou quando ela se tornou obsoleta.
- Since:
-
Descrição de desde qual versão do código a API está disponível.
- Deprecated:
-
Parágrafo denotando que esta função deveria não mais ser usada. A descrição deveria apontar o leitor para a nova API.
Você também pode adicionar informação sobre estabilidade em todos os elementos de documentação para indicar se a estabilidade de uma API é garantida para eles para futuros lançamentos menores do projeto.
O nível de estabilidade padrão para todos os elementos de documentação pode ser definido passando o argumento --default-stability para gtkdoc-mkdb com um dos balores abaixo.
- Stability: Stable
-
Marca o elemento como estável. Isto é para APIs públicas cuja estabilidade é garantida para todos os próximos lançamentos menores do projeto.
- Stability: Unstable
-
Marca o elemento como instável. Isto é para APIs públicas que são publicados como versão de desenvolvimento antes de se tornar estável.
- Stability: Private
-
Marca o elemento como privado. Isto é para interfaces que podem ser usadas por um conjunto pequeno de módulos, mas não por terceiros.
/** * foo_get_bar: * @foo: Um foo * * Obtém o bar do @foo. * * Returns: bar do @foo * * Since: 2.6 * Deprecated: 2.12: Use foo_baz_get_bar() no seu lugar. */ Bar * foo_get_bar(Foo *foo) { ...
3.3.2. Anotações
Blocos de documentação podem conter tags de anotação. Essas tags serão renderizadas com dicas de ferramentas descrevendo seu significados. As tags são usadas pelo gobject-introspection para garantir associações (bindings) de linguagens. Uma lista detalhada tags aceitas podem ser encontrada no wiki.
/** * foo_get_bar: (anotação) * @foo: (anotação): algum foo * * Obtém bar do @foo. * * Returns: (anotação): bar do @foo */ ... /** * foo_set_bar_using_the_frobnicator: (anotação) (outra anotação) * (e uma outra anotação) * @foo: (anotação) (uma outra anotação): algum foo * * Define bar no @foo. */
3.3.3. Bloco de comentário de função
Por favor, lembre-se de:
- Documente se objetos, listas, strings, etc. retornados devem ser não usados/não referenciados/liberada.
- Documente se parâmetros pode ser NULL e o que acontece se eles o forem.
- Mencione pré-condições e pós-condições interessantes onde for apropriado.
Gtk-doc presume que todos os símbolos (macros, funções) começando com “_” são privadas. Elas são tratadas como funções estáticas.
/** * nome_da_função: * @par1: descrição do parâmetro 1. Esta pode se estender por mais de * uma linha. * @par2: descrição do parâmetro 2 * @...: uma lista de bars terminada em %NULL * * A descrição da função vai aqui. Você pode usar @par1 para se referir a parâmetros * de forma que eles ficam em destaque na saída. Você também pode usar %constant * para constantes, nome_da_função2() para funções e #GtkWidget para links para * outras declarações (que pode ser documentada em outro lugar). * * Returns: um inteiro. * * Since: 2.2 * Deprecated: 2.18: Use outra_função() em seu lugar. */
- Returns:
-
Parágrafo descrevendo o resultado retornado.
- @...:
-
No caso da função possuir argumentos variados, você deveria usar esta tag (@Varargs: também funciona por motivos de histórico).
3.3.4. Bloco de comentário de propriedade
/** * AlgumWidget:alguma-propriedade: * * Aqui você pode documentar uma propriedade. */ g_object_propriedade_install_classe (object_classe, PROP_ALGUMA_PROPRIEDADE, ...);
3.3.5. Bloco de comentário de sinal
Por favor, lembre-se de:
- Documente quando o sinal é emitido e se ele é emitido antes ou após outros sinais.
- Documente o que um aplicativo pode fazer no manipulador do sinal.
/** * FooWidget::foobarizado: * @widget: o widget que recebeu o sinal * @foo: algum foo * @bar: algum bar * * O sinal ::foobarized é emitido cada vez que alguém tenta foobarizar @widget. */ foo_sinais[FOOBARIZAR] = g_signal_novo ("foobarizar", ...
3.3.6. Bloco de comentário de struct
/** * FooWidget: * @bar: algum #gboolean * * Este é o melhor widget, já mais visto. */ typedef struct _FooWidget { GtkWidget parent_intance; gboolean bar; } FooWidget;
Use /*< private >*/ antes dos campos da struct privada que você deseja esconder. Use /*< public >*/ para o comportamento inverso.
Se o primeiro campo for “g_iface”, “parent_instance” ou “parent_class”, ele será automaticamente considerado como privado e não precisará ser mencionado no bloco de comentário.
Blocos de comentário de struct também podem ser usados para GObjects e GObjectClasses. É normalmente uma boa ideia adicionar um bloco de comentário para uma classe, se ela possui vmethods (pois assim é como elas podem ser documentadas). Para o próprio GOBject pode-se usar os documentos de seção relacionados, tendo um bloco separado para a instância do struct seria útil se a instância possui campos públicos. Uma desvantagem aqui é que isso cria duas entradas no índice do mesmo nome (a estrutura e a seção).
3.3.7. Bloco de comentário de enum
/** * Alguma coisa: * @ALGUMACOISA_FOO: alguma coisa foo * @ALGUMCAOISA_BAR: alguma coisa bar * * Valores de enum usados para a coisa, para especificar a coisa. */ typedef enum { ALGUMACOISA_FOO, ALGUMACOISA_BAR, /*< private >*/ ALGUMACOISA_CONTAGEM } Alguma coisa;
Use /*< private >*/ antes de valores privados de enum que você deseja ocultar. Use /*< public >*/ para o comportamento inverso.