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. Bloco de comentário de função
- 3.3.3. Bloco de comentário de propriedade
- 3.3.4. Bloco de comentário de sinal
- 3.3.5. Bloco de comentário de struct
- 3.3.6. 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.
(CORRIJA-ME : Informação sobre estabilidade)
/** * 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. 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.
Também, dê uma olhada nas tags de anotação do GObject Introspection: http://live.gnome.org/GObjectIntrospection/Annotations
/** * 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 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.3. 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.4. 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.5. Bloco de comentário de struct
/** * FooWidget: * @bar: algum #gboolean * * Este é o melhor widget, já mais visto. */ typedef struct _FooWidget { /*< private >*/ GtkWidget parent; /*< public >*/ gboolean bar; } FooWidget;
Use /*< private >*/ antes dos campos da struct privada que você deseja esconder. Use /*< public >*/ para o comportamento inverso.
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.6. 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.