Documentando o código

GTK-Doc usa comentários do código fonte com uma sintaxe especial para documentação do código. Além disso, ele obtém informações sobre a estrutura do seu projeto a partir de outros fontes. Na próxima seção, você vai descobrir todas as informações sobre a sintaxe dos comentários.

Localização da documentação

Antigamente, a maioria das documentações tinha que ser preenchida em arquivos residentes dentro do diretório tmpl. Isso tem as desvantagens das informações frequentemente não serem atualizadas e também que o arquivo tende a causar conflitos com sistemas de controle de versão.

Para evitar os problemas mencionados a seguir nós sugerimos que a documentação seja colocada dentro das fontes. Este manual vai apenas descrever esta forma de documentar código.

A varredura sabe lidar com a maioria dos cabeçalhos de C sem problemas. Caso se receba avisos (warnings) na varredura que pareça ser um caso especial, pode-se informar ao GTK-Doc para ignorá-los.

Example 3-1Bloco de comentário do GTK-Doc
#ifndef __GTK_DOC_IGNORE__
/* código não analisável arqui */
#endif