Documentação gerada automaticamente para o código MQL5

1. Introdução

A maioria dos codificadores Java estará familiarizada com a documentação gerada automaticamente com o JavaDocs. A ideia é adicionar comentários no código de uma maneira semi-estruturada que possam ser extraídos em um arquivo de ajuda fácil de navegar.

O mundo do C++ também possui vários geradores automáticos de documentação, com os dois líderes sendo o SandCastle da Microsoft e o Doxygen. Eu decidi ver de que forma o Doxygen documentaria o MQL5, que é, basicamente, um subconjunto personalizado do C++. Para mim, esta é uma importante etapa na maturidade do MQL5, porque a complexidade da linguagem é facilmente capaz de conceber algumas bibliotecas de classe bem grandes.

O experimento funcionou muito bem, acredito que a documentação de ajuda que o Doxygen produz do código MQL5 irá agregar uma grande quantidade de valor.

2. Doxygen

O Doxygen é um gerador de documentação automático open source disponível sob a licença GNU (General Public License - Licença Pública Geral), o que significa que seu desenvolvimento tem sido similar ao de outros projetos open source, como Linux e Mozilla. O Doxygen é livre para download e uso, seu código fonte é aberto para que qualquer pessoa possa visualizar, foi desenvolvido e está sendo melhorado como uma colaboração entre vários desenvolvedores que dedicaram seu tempo.

Como seu nível mais básico de utilização, o Doxygen simplesmente interpreta todo o código C++ (ou MQL5) em um projeto e exibe sua estrutura em um arquivo de fácil navegação. Isso é particularmente útil com codesets orientados a objeto, que tendem a ter uma grande hierarquia de classe e um grande número de funções de membro. Para o uso completo dos recursos do Doxygen, comentários estruturados também devem ser escritos no código, de modo que o Doxygen possa lê-los e adicionar informações no arquivo de ajuda gerado.

2.1 Download do Doxygen

A homepage do Doxygen é http://www.doxygen.org/. A partir de lá, você pode navegar para a página de download e baixar a última versão para Windows. No momento em que isto é escrito, a versão é Doxygen 1.6.1, veja abaixo

Figura 1. Download do Doxygen

2.2 Configuração e execução do Doxygen

Pequenas exigências a serem feitas, exceto adicionar os tipos de arquivos *.mqh e *.mq5 e ativar a geração da ajuda HTML. As próximas cinco figuras acompanham a configuração.

As primeiras quatro capturas de tela (Figuras 2 a 5) mostram as telas do Assistente:

Figura 2. Configuração do Doxygen - Assistente 1

Figura 3. Configuração do Doxygen - Assistente 2

Figura 4. Configuração do Doxygen - Assistente 3

Figura 5. Configuração do Doxygen - Assistente 4

Finalmente, há uma troca de nível técnico, adicionar os tipos de arquivo mqh e mq5:

Figura 6. Configuração do Doxygen - incluindo arquivos mqh e mq5

E agora, está pronto para rodar. Observe que o Doxygen irá armazenar e ler um arquivo de configuração, que está incluso no anexo zip deste artigo.

Figura 7. Executando o Doxygen

2.3 Usando o Doxygen

O Doxygen possui um excelente arquivo de ajuda html (construído, é claro, com Doxygen - aqui está a versão html original) no qual detalha um incrível conjunto de recursos de documentação, incluindo exibição perfeita de fórmula matemática complexa. Entretanto, a ferramenta também pode ser usada eficientemente de uma forma muito simples para criar arquivos úteis de ajuda.

Aqui está um exemplo da função CiMACD::Create() em MQL5/Include/Oscilators.mqh. Observe que estes arquivos indicadores não eram originalmente parte da distribuição beta anterior e você pode precisar baixar novamente o MetaTrader 5 para vê-los.

//+------------------------------------------------------------------+
//| Create indicator "Moving Averages Convergence-Divergence".       |
//| INPUT:  symbol          -chart symbol,                           |
//|         period          -chart period,                           |
//|         fast_ema_period -period fast EMA,                        |
//|         slow_ema_period -period slow EMA,                        |
//|         signal_period   -period signal MA,                       |
//|         applied         -what used.                              |
//| OUTPUT: true-if successful, false otherwise.                     |
//| REMARK: no.                                                      |
//+------------------------------------------------------------------+
bool CiMACD::Create(string symbol,
                    ENUM_TIMEFRAMES period,
                    int fast_ema_period,
                    int slow_ema_period,
                    int signal_period,
                    int applied)

Algumas simples mudanças nas palavras-chave preparam os comentários para interpretação pelo Doxygen. Os comentários têm agora três barras (///), INPUT: mudou para \param, e OUTPUT: para \return

//+------------------------------------------------------------------+
/// Create indicator "Moving Averages Convergence-Divergence".        
/// \param  symbol          -chart symbol,                            
/// \param  period          -chart period,                            
/// \param  fast_ema_period -period fast EMA,                         
/// \param  slow_ema_period -period slow EMA,                         
/// \param  signal_period   -period signal MA,                        
/// \param  applied         -what used.                               
/// \return true-if successful, false otherwise.                      
//+------------------------------------------------------------------+
bool CiMACD::Create(string symbol,
                    ENUM_TIMEFRAMES period,
                    int fast_ema_period,
                    int slow_ema_period,
                    int signal_period,
                    int applied)

E então, quando o Doxygen processar isso, o arquivo de ajuda será semelhante ao da Figura 8:

Figura 8. CiMACD::Create() como visto no HTML gerado por Doxygen

2.4 Usando o Doxygen no codeset MQL5 completo

O Doxygen é excelente na criação de arquivo de ajuda para grandes projetos. São mais de cem arquivos .mq5 e mqh distribuídos com o MetaTrader 5 sob a pasta do MQL5, onde muitos são interrelacionados.

Escrevi um script utilitário MetaquotesCommentsToDoxygen.mq5 (incluso no arquivo zip anexo) que apresenta os Metaquotes básicos para as conversões de comentário do Doxygen destacadas acima. Esta não é uma etapa essencial para produzir um arquivo de ajuda, mas fornece uma demonstração dos úteis recursos da documentação adicional do Doxygen.

O procedimento que usei para criar um arquivo de ajuda codeset MQL5 é o seguinte

• Copiei a pasta e subpastas MQL5 em MQL5/files
• Removi MQL5/files/MQL5/Include/Strings/string.mqh - por um motivo desconhecido este arquivo impede que o Doxygen conclua sua análise de código

Opcional para documentação adicional dos comentários estruturados:

• A partir da pasta MQL5/Files, execute o comando Windows/DOS xcopy *.mq* c:\ /S/L > MQL5codeList.txt
• Execute o script MetaquotesCommentsToDoxygen.mq5 em qualquer tabela

A documentação de ajuda resultante é de boa qualidade e rapidamente demonstra sua utilidade - As Figuras 9 a 12 são uma amostra do que você pode ver.

Figura 9. Lista de classe gerada pelo Doxygen

Figura 10. Diagrama em árvore da classe gerada pelo Doxygen para CArrayObj

Figura 11. Lista de funções do membro gerado pelo Doxygen para CArrayObj

Figura 12. Lista Definir gerada pelo Doxygen

3. HTML Help Workshop Microsoft

Há mais uma etapa necessária para tornar o produto do Doxygen ainda mais útil. O Doxygen produz um arquivo index.html que aponta para um grande número de outros arquivos html e imagens. Isso é essencialmente um pequeno website e, consequentemente, muito trabalhoso para distribuir.

Muito tempo atrás, a Microsoft reconheceu que arquivos de ajuda para aplicações Windows devem ser escritos em html, então, para este propósito, desenvolveu seu HTML Help Workshop. O HTML Help Workshop pega um conjunto de arquivos de ajuda, como o resultante do Doxygen e compila tudo em um único arquivo .chm. Este é o mesmo formato dos arquivos de ajuda distribuídos com o MetaTrader 5.

3.1 Download do HTML Help Workshop

Você pode baixar e instalar o htmlhelp.exe na página da Microsoft aqui.

Figura 13. Download do HTML Help

3.2 Fazendo um arquivo de ajuda HTML compilado

O produto do processamento do Doxygen pode facilmente ser convertido pelo HTML Help Workshop em um arquivo de ajuda html compilado. Como configurado para este artigo, o Doxygen cria um arquivo index.hhp pronto para o HTML Help Workshop abrir, como mostrado abaixo na Figura 14.

Figura 14. Local do arquivo index.hhp gerado pelo Doxygen

A próxima etapa é compilar:

Figura 15. Compilando com o HTML Help

... e quando terminado, o novo arquivo index.chm pode ser copiado na pasta MetaTrader 5/Help e renomeado, como mostrado abaixo nas Figuras 16 e 17.

Figura 16. Local do index.chm

Figura 17. index.chm copiado em uma pasta de ajuda e renomeado

4. Resumo

Este exercício me convenceu a usar o Doxygen ou um equivalente no futuro para documentar qualquer código MQL5, de modo que quero que as pessoas entendam e usem, espero que outras pessoas também.

Apêndice. Descrição dos arquivos no files.zip do Doxygen em anexo

Arquivo	Descrição	Copiar para
Codeset MQL5 help.chm	Arquivo de ajuda HTML compilado de todos os códigos distribuídos com o MetaTrader 5 build 229, 8 de dezembro de 2009.	MetaTrader 5/Help
MetaquotesCommentsToDoxygen.mq5	Script que muda os comentários no código MQL5 para possibilitar a interpretação do Doxygen dos mesmos	MQL5/Scripts
MQL5codeList.txt	Uma lista de todos os arquivos MQL5 distribuídos	MQL5/Files
MQL5_Doxygen	Arquivo de configuração do Doxygen	MQL5