====== 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 [[http://www.stack.nl/~dimitri/doxygen/commands.html|link]].

Veja algumas dicas:

  - 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**
  - 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//
  - 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''
  - Para forçar uma quebra de linha (<br/>), basta inserir o comando ''\n''
  - Para usar uma lista sem numeração (como os exemplos acima), preceda cada termo com ''-'' ou o comando ''\li''. Exemplo: 
<code>
- OracleSpatial
- PostgreSQL
- PostGIS </code> ou <code>
\li OracleSpatial
\li PostgreSQL
\li PostGIS </code> fica: 
    * OracleSpatial
    * PostgreSQL
    * PostGIS

===== Personalizando o arquivo de configuração =====

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:
  - Crie um arquivo ''terraOGC/src/meu_doc_config'' na pasta src
  - Inclua o arquivo padrão do TerraOGC <code apache>
@INCLUDE = terraogc_doc_config
</code>
  - Coloque seus parâmetros personalizados em seguida. <code apache>
PROJECT_NUMBER         = 0.1.3
</code>


==== Exemplo ====

O exemplo a seguir vai permitir que a documentação em JavaScript seja completamente processada numa máquina Linux com o [[http://www.gnu.org/software/gawk/|Gawk]] instalado:
<code apache>
# Configuracao personalizada do Doxygen
# Inclui arquivo principal
@INCLUDE = terraogc_doc_config

# Sobrepoe propriedades padrao
FILTER_PATTERNS = *.js=../scripts/js2pseudocpp.awk
</code>

Para máquinas Windows, basta instalar uma versão Win32 do Gawk, que pode ser encontrada no [[http://gnuwin32.sourceforge.net/|GNU Win 32]] ([[http://gnuwin32.sourceforge.net/packages/gawk.htm|link direto]]). Em seguida troque o valor do parâmetro ''FILTER_PATTERNS'' conforme segue: <code apache>
FILTER_PATTERNS = ..\scripts\js2pseudocpp.bat drive:\path\to\awk.exe
</code>





===== Integrando com a documentação da TerraLib =====

Use este {{twsg:dicas:terralib_doc_config.txt|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: <code apache>
EXTERNAL_GROUPS        = NO
TAGFILES               =../../terralib/doc/terralib.tag=../TerraLib
</code>

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: <code>
htdocs
 |
 |--TerraOGC (pasta de documentação html do TerraOGC)
 |
 |--TerraLib (pasta de documentação html da TerraLib)
</code>