Dicas Doxygen

Documentar bem o código é essencial para o sucesso do projeto. Uma boa referência para os comandos Doxygen pode ser encontrada no link.

Veja algumas dicas:

1. Para obter o efeito de negrito, você pode usar o comando \b antes da palavra que deseja destacar. Para mais de uma palavra use como em HTML. Exemplos:
   • \b must ⇒ must
   • <b>must use</b> ⇒ must use
2. Para destacar uma palavra em itálico use o comando \a. Para múltiplas palavras coloque entre as tags <i> e </i>. Exemplos:
   • \a loadInstances ⇒ loadInstances
   • <i>loadInstances method</i> ⇒ loadInstances method
3. Para um efeito de fonte monospace, use o comando \c. Para múltiplas palavras use as tags <tt></tt>. Exemplos:
   • \c sessionId ⇒ sessionID
   • <tt>sessionId parameter</tt> ⇒ sessionID parameter
4. Para forçar uma quebra de linha (<br/>), basta inserir o comando \n
5. Para usar uma lista sem numeração (como os exemplos acima), preceda cada termo com - ou o comando \li. Exemplo:

- OracleSpatial
- PostgreSQL
- PostGIS 

ou

\li OracleSpatial
\li PostgreSQL
\li PostGIS 

fica:

• OracleSpatial
• PostgreSQL
• PostGIS

O arquivo padrão de configuração para o Doxygen no TerraOGC é o terraOGC/src/terraogc_doc_config. Você pode criar um arquivo personalizado e incluir suas configurações sem precisar alterar o arquivo que consta no CVS.

Faça o seguinte:

1. Crie um arquivo terraOGC/src/meu_doc_config na pasta src
2. Inclua o arquivo padrão do TerraOGC

   @INCLUDE = terraogc_doc_config

3. Coloque seus parâmetros personalizados em seguida.

   PROJECT_NUMBER         = 0.1.3

O exemplo a seguir vai permitir que a documentação em JavaScript seja completamente processada numa máquina Linux com o Gawk instalado:

# Configuracao personalizada do Doxygen
# Inclui arquivo principal
@INCLUDE = terraogc_doc_config
 
# Sobrepoe propriedades padrao
FILTER_PATTERNS = *.js=../scripts/js2pseudocpp.awk

Para máquinas Windows, basta instalar uma versão Win32 do Gawk, que pode ser encontrada no GNU Win 32 (link direto). Em seguida troque o valor do parâmetro FILTER_PATTERNS conforme segue:

FILTER_PATTERNS = ..\scripts\js2pseudocpp.bat drive:\path\to\awk.exe

Use este arquivo de configuração do Doxygen para a TerraLib. Ponha na pasta terralib/src/terralib e rode o Doxygen para gerar a documentação em terralib/doc.

Para integrar com a documentação do TerraOGC, use o comando TAGFILES no seu arquivo personalizado de documentação, acrescentando:

EXTERNAL_GROUPS        = NO
TAGFILES               =../../terralib/doc/terralib.tag=../TerraLib

O parâmetro ../TerraLib no TAGFILES indica a localização da pasta terralib/doc/html. Pode ser absoluto ou relativo. Neste caso usei o relativo pois uso uma estrutura do tipo:

htdocs
 |
 |--TerraOGC (pasta de documentação html do TerraOGC)
 |
 |--TerraLib (pasta de documentação html da TerraLib)