Introdução

Qualquer desenvolvedor mais cedo ou mais tarde enfrenta a necessidade de criar documentação para seu trabalho. A escrita de instruções e guias são parte integrante da comunicação com o cliente, bem como das atividades diárias. Além disso, com o tempo, acumulá-se um monte de trechos de código e bibliotecas, que até podem ser de outra pessoa. É a execução cuidadosa da documentação que ajuda a lidar com todo esse material. Se, ao escrever o código, se tiver em mente a necessidade processar material de referência, o tempo gasto nisso será reduzido a zero. Comentários e tags necessários são colocados durante a criação do código. À primeira vista, esse trabalho parece ser opcional, mas se for feito, ajudará o desenvolvedor a poupar muito tempo e nervos.

Consideremos o processo de criação de documentação do começo ao fim, parando em pontos importantes. Anteriormente já foi escrito um artigo sobre o assunto, mas não todas as informações nele contidas estão atualizadas e nem todos os métodos nele são eficientes. Tentaremos desenvolver e continuar o tema. Basicamente, estudaremos o uso do programa Doxygen, usando Doxywizard.exe:

Adicionando arquivos MQL no Doxygen

Nosso objetivo é obter um arquivo de referência/de apresentação para o código já escrito, localizado num ou mais arquivos com uma marcação já aplicada. Como resultado será obtido um arquivo no formato chm. Além disso, criaremos arquivos em formato HTML, que poderão lidar sozinhos tanto com tarefas de apresentação como de referência. Como eu disse, vamos usar o programa Doxygen, uma vez que é adequado para nossos propósitos.

A descrição do processo de instalação do programa e da saída do arquivo final é mostrado no artigo referido, porém desde a sua publicação tem passado muito tempo, e se nós agora fizermos tudo da forma como é descrito lá, nada vai dar certo. Embora o programa esteja processando, não haverá comentários ou mensagens de erro e, mais importante, nenhum arquivo será criado.

Por isso, a primeira coisa que faremos será resolver este problema fazendo ajustes na configuração do programa. Executamos doxywizard.exe e começamos a configuração, especificamos o nome do projeto, a pasta de entrada e de saída. Necessariamente devemos marcar "Optimize for C++ output" na opção Mode, na aba Wizard.

Vamos para a aba Expert e na opção Input adicionamos os arquivos com a extensão apropriada:

Agora o Doxygen saberá que ele tem que realizar a análise sintática dos arquivos com nossa extensão, mas isso não será suficiente! É preciso especificar ao programa que os arquivos com a extensão .mq* são um análogo dos arquivos com a extensão .c, para executar a "exibição" de extensões (talvez essa ação possa ser chamada desse modo):

Deste ponto em diante, o Doxygen começa a parsear nossos arquivos e retornar um resultado.

Codificação

Vamos falar sobre uma fonte de problemas associados com a codificação dos documentos iniciais e finais.

Se o idioma da documentação for o Inglês, não haverá nenhum problema. No entanto, se quisermos obter a documentação em outra língua, veremos símbolos ilegíveis, uma vez que, por padrão, todos os documentos são considerados como se fossem criados em UTF-8. Se, de fato, parte dos documentos têm outra codificação, o texto torna-se-ia ilegível. Examinemos a solução:

1. Definimos o idioma e a codificação padrão. Neste caso, será UTF-8 e língua russa:
   

   

   
   

   Note-se que não consegui fazer a alteração DOXYFILE_ENCODING. Seja qual for a codificação especificada, no campo de entrada ela é substituída por UTF-8. Talvez seja possível substituir a codificação neste lugar apenas de uma maneira, isto é, registrando-a no arquivo pelo qual "Head" deve ser substituído por padrão (isso foi discutido acima). No entanto, é pouco provável que se possa alcançar o resultado desejado dessa maneira,

2. Não necessariamente devemos especificar UTF-8 para a codificação dos documentos iniciais. No nosso caso, pelo contrário, é a codificação CP1251. Se uma parte dos documentos for criada numa codificação e outra parte, noutra, então transcodificaremos os arquivos para que todos os documentos iniciais fiquem apenas com uma codificação, e registramo-la no campo de entrada:
3. E, finalmente, se pretendermos concluir em formato CHM (um tipo de arquivo de ajuda), teremos que especificar qual a codificação será usada no índice do HtmlHelp (arquivo com extensão hhk):
   

   

   Para aqueles que querem uma visão ainda mais detalhada sobre esta questão, anexo um artigo sobre como criar uma documentação em espanhol e inglês usando Doxygen.

Passaremos a considerar agora os pontos mais gerais e mais relevantes, em particular, a aparência do arquivo HTML gerado.

Cabeçalho e "porão" de página

As opções disponíveis estão localizadas na aba Expert, na opção HTML. Os alternadores que permitem conectar os arquivos html personalizados - campos HTML_HEADER, HTML_FOOTER e HTML_STYLESHEET - à criação de documentação final são bem úteis. Cada nome é uma referência clara da função de cada um deles - cabeçalho, pé de página (porão de página) e estilo de exibição. Lembro que, para que os arquivos html sejam gerados, deve ser marcado o alternador GENERATE_HTML nesta aba.

Ambos os arquivos html considerados aqui são escritos segundo regras especiais, embora meu arquivo footer.html execute apenas um pedaço de texto html, sem cabeçalho e registro, somente desta maneira:

<div>
  <h1 style="text-align: center;">Footer</h1>
</div>

Mas é melhor aderir às regras. Para entender exatamente como podem estar dispostos os arquivos do usuário, podemos gerar os usados ​​pelo programa por padrão. Obteremos não só os dois arquivos HTML desejados, mas também uma folha de estilo. Fazemos isso com o comando:

 - doxygen -w html new_header.html new_footer.html new_stylesheet.css

Esse é um trecho do arquivo new_footer.html:

<!-- HTML footer for doxygen 1.8.13-->
<!-- start footer part -->
<!--BEGIN GENERATE_TREEVIEW-->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    $navpath
    <li class="footer">$generatedby
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="$relpath^doxygen.png" alt="doxygen"/></a> $doxygenversion </li>
  </ul>
</div>
<!--END GENERATE_TREEVIEW-->
<!--BEGIN !GENERATE_TREEVIEW-->
<hr class="footer"/><address class="footer"><small>
$generatedby &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="$relpath^doxygen.png" alt="doxygen"/>
</a> $doxygenversion
</small></address>

Imediatamente chamam a atenção vários espaços reservados, cujas lista e propósito deverão estar disponíveis na documentação. É fácil ver onde exibida a publicidade do Doxygen e onde você pode colocar seu link. Da mesma forma, será possível corrigir o new_header.html e, se desejar, também a folha de estilo, para conectá-los em série na aba especificada. Assim, é possível alterar significativamente a aparência da documentação final segundo seus próprios propósitos.

Pré-processamento

O Doxygen permite pré-processar arquivos. Isto é feito para permitir que o programa processe macros do tipo BEGIN_MESSAGE_MAP e construções do tipo __declspec a partir do Visual Studio. Para nossos scripts, isso não é tão importante, é por isso que estamos aqui simplesmente mencionando esta possibilidade, sem entrar em detalhes. Este mecanismo é configurado na opção Preprocessor, na aba Expert. Mencionamos também que é possível criar filtros externos cuja finalidade consiste em converter o arquivo de entrada para que o Doxygen possa entendê-lo. Esse filtro é um programa de console externo, a cuja cadeia de caracteres de comando é adicionado o nome do arquivo. O programa de filtro em si é basicamente um conjunto de expressões regulares que convertem, por exemplo, um programa em assembler. O desenvolvedor deve resolver se deve aplicar o pré-processamento ou não. É possível, por exemplo, por meio deste mecanismo, tentar tornar claro, para Doxygen, o construção #property.

Conectando exemplos

A possibilidade de adicionamento na documentação de exemplos parece muito interessante. Isto é opcional, mas faz uma documentação completa e lhe da uma aparência profissional. Exemplos são ligados ao projeto na forma de um ou mais arquivos. Para fazer isso, na página do código - para a qual o desenvolvedor gostaria de dar um exemplo - deve ser colocado esta construção:

/** \example filename.ext
 * This is an example of how to use ....
 */

Aqui é definido o nome do arquivo com exemplos. Na segunda cadeia de caracteres, é possível listar quais funções e classes são exemplificadas. Mas isso não é suficiente, uma vez que falta saber onde o arquivo está localizado. O caminho para o arquivo com exemplos deve ser indicado claramente no Doxygen. Isso é feito como mostrado na figura, isto é, especificamos o caminho para o arquivo e os padrões de seus nomes:

Adicionando vários caminhos e usando a opção EXAMPLE_RECURSIVE é possível conectar à nossa documentação um conjunto de arquivos com exemplos, trazendo assim como resultado um guia bem desenvolvido.

Tags HTML

Outra habilidade útil do Doxygen tem a ver com o trabalho com fragmentos de marcação HTML que podem ser colocados diretamente nos blocos de comentário. A documentação do programa tem uma lista muito respeitável de tags HTML que podem lidar com o Doxygen e colá-lo no documento final. Por exemplo, aqui há um texto que deve ser inserido na descrição da macro e uma tabela com cabeçalho:

/*!
  \def def_example
  \brief <a href="http://www.google.com">links to google</a>
         <table>
           <caption>Single table</caption>
           <tr>
             <td>One</td>
             <td>two</td>
           </tr>
         </table>
*/
#define def_example "Some define"

Juntamente com a marcação html podem ser utilizados pseudo-símbolos do tipo  

Quando se usam links aparece mais uma particularidade, isto é, o Automatic link generation. Na prática, isto significa que o Doxygen converterá um texto do tipo https://www.mql5.com num link correto e colocá-lo-á no documento final. Assim, a transformação do Automatic link generation não é limitado. É possível criar links para arquivos, classes, funções individuais. Isso serve para criar seções de documentação do tipo "See Also".De modo geral, essa marcação permitirá uma melhor descrição do pedaço desejado de código, o uso para marcar o tipo de "Prev/Next" e formas mais avançadas de paginação, bem como servir para o benefício do SEO e da publicidade.

Folha de rosto

Acima tem sido dito sobre a possibilidade de substituir - pelo seu próprio - o código no cabeçalho e no "porão" das páginas. Além disso, o desenvolvedor tem a oportunidade de desenvolver um design separado para a folha de rosto. Para fazer isso, ele deve especificar num dos arquivo que o conteúdo é uma folha de rosto. Isso é feito usando a tag \mainpage incluída no início do arquivo:

/*! \mainpage My Personal Index Page
* \image html i.jpg
 */

Nessa marcação é declarado que o arquivo em que está localizada é uma folha de rosto com o cabeçalho "My Personal Index Page", após o qual será inserida a imagem "i.jpg". A imagem deve ser preparada com antecedência, enquanto o caminho para ele tem de ser conhecido pelo Doxygen:

Além de imagens, podem ser inseridos arquivos e outros tipos.

Saída em formato html e HtmlHelp

A documentação pode ser criada em vários formatos. Na aba Wizard, na opção Output, é possível marcar os necessários. Em primeiro lugar, é criada a documentação em html. Na pasta especificada com de saída será criado o arquivo index.html. Ele será o arquivo principal de toda a documentação. No entanto, este formato não é sempre conveniente. Por isso, consideramos a criação de documentação no formato HtmlHelp. Para fazer isso, é necessário marcar o alternador de HTML e "prepare for compressed HTML" no mesmo lugar e na mesma aba. Além disso, na aba Expert, na opção HTML, na caixa de edição CHM_FILE, definimos o nome do arquivo HtmlHelp do guia com extensão, enquanto na caixa de edição abaixo (HHC_LOCATION) definimos o caminho de acesso ao compilador do guia hhc.exe. Este parâmetro é opcional. Se o campo for deixado em branco, serão preparados todos os arquivos necessários, enquanto o guia no formato chm terá que ser obtido através de uma chamada separada do programa HTML Help Workshop.

Nesse caso, há também algumas opções para ajuste fino. Particular atenção deve ser dada ao GENERATE_CHI. Por padrão, esse alternador é descartado. Mas se ele estiver definido, o Doxygen gerará um arquivo de índice separado com extensão CHI. Se, posteriormente, for excluído esse arquivo, será extremamente difícil o uso do arquivo principal do guia. Quase todo o guia em formato HtmlHlp perderá a maior parte da funcionalidade.

Já foi dito como configurar as codificações. Resta ir para a aba Run e clicar no botão "Run Doxygen". Após uma página inteira de mensagens técnicas, o Doxygen notificará a conclusão do trabalho. Abaixo aparece o botão "Show HTML output" para ver os documentos no browser. Será necessário encontrar e executar manualmente o arquivo no formato HtmlHelp.

Um pequeno vídeo para trabalhar com o Doxywizard:

A seguir, vamos olhar algumas coisas secundárias, mas interessantes.

Recursos do editor Sublime Text 3 para a colocação de tags no código em linguagem MQL5

Para que o Doxygen funcione, é necessária a colocação de tags especiais no texto do programa documentado. Tags são dispostos em comentários de várias (ou uma) strings para seções individuais de código, classes, macros, funções, etc. Quanto mais informações quer transmitir o desenvolvedor na documentação, mas cuidadosamente é necessário estruturar e mais complexo é o resultado.

A colocação tem de ser feita no editor MT5. Ao fazer isto, é necessário acompanhar atentamente erros emergentes. Este processo pode ser um pouco simplificado e parcialmente automatizado. Usamos o editor Sublime Text 3. Ele reconhece linguagem MQL4, e pode, portanto, trabalhar com linguagem MQL5. Conectamos no editor ambos os pacotes relevantes para MQL.

Em seguida, definimos um pacote capaz de trabalhar com a marcação desejada, isto é, DoxyDoxygen. Ele tem teclas de atalho, ele pode realizar a tradução para diferentes idiomas e autocompletar. Este pacote ajudará a colocar corretamente todas as tags necessárias, mais rapidamente e a um custo menor. Como escrito na documentação (ele pode ser encontrado no arquivo em anexo), após a marcação, o Doxygen pode ser chamado diretamente a partir do editor. Além disso, na documentação anexa, é possível encontrar uma descrição do processo de configuração do pacote.

Em geral, para trabalhar com o pacote descrito, não há problemas especiais, sutilezas e coisas do genro, por isso não vou me debruçar sobre isso.

Formatos de saída: pdf e djvu

Embora o Doxygen venha com este recurso interessante, o trabalho em sua aplicação ainda não foi concluído. Agora é possível tentar exibir documentos nestes formatos, uma vez que na documentação do Doxygen há algumas informações sobre isso, bem como existem alguns artigos e instruções em sites de terceiros. Aqui, consideramos a saída em formato pdf um pouco mais detalhadamente.

1. Na aba Wizard, na opção Output, é possível marcar a exibição no formato LaTeX e selecionar o formato "for PDF". Na documentação está escrito que se deve marcar GENERATE_PERLMODE na aba Expert na opção PerlMod, mas vamos pular esse passo.
2. Levamos a cabo outras definições necessárias, incluindo o ajuste de saída em formatos CHM e html (se necessário).
3. Criamos os documentos necessários.

Na pasta de saída, será criada a pasta latex, nela serão colocados os arquivos desse formato. Aqui termina o trabalho com o Doxygen. Agora é necessário converter os arquivos do formato latex para o formato PDF. Eu usei o programa MikTex, tomado aqui no formato portable. Instalamos e executamos o programa. Selecionamos nele TeXworks. Na janela do editor, procuramos e abrimos o arquivo refman.tex, que foi criado - para nós - pelo Doxygen na pasta latex. A seguir, na barra de ferramentas do editor, na lista combinada, selecionamos XeLaTex e clicamos no botão verde grande à esquerda. Observamos uma série de mensagens de diagnóstico. Durante a operação, o editor pedirá instalar pacotes adicionais (é necessário concordar). Se a saída falhar, você pode tentar novamente a "compilação".

Como resultado, nessa mesma pasta latex, será criado o arquivo refman.pdf com nossa documentação. A qualidade de saída é pobre. É óbvio que é preciso editar ainda mais o design. Talvez muitos dos problemas poderiam ser evitados editando os arquivos de origem látex. No entanto, não nos esqueçamos de que o trabalho sobre a implementação desse recurso ainda não está completo, então esperamos a conexão oficial da opção ao Doxygen.

Uso prático

Voltemo-nos para exemplos específicos e, assim, mostraremos como se pode usar o Doxygen e outros programas para a criação de documentos. Comecemos por criar a documentação para a biblioteca padrão - um conjunto de classes no \MQL5\Include. Usamos uma forma simples, isto é, executaremos o programa Doxygen em todos os arquivos, sem colocar tags adicionais nos próprios arquivos. Ao fazer isto, não teremos chance de receber informações adicionais importantes sobre os elementos da biblioteca, mas veremos o que podemos obter. Talvez fiquemos satisfeitos com o resultado obtido. Para começar, assumiremos que todos os componentes de software necessários já estão instalados no computador. Vamos a isso:

Em qualquer caso seremos prudentes e copiaremos e colaremos a biblioteca padrão em qualquer outra pasta. Durante o trabalho não deverá haver quaisquer entradas nos arquivos, é melhor não arriscar.

• Executamos o Doxygen e começamos sua configuração. Para uma configuração preliminar, é possível utilizar o arquivo anexado MQL5Doxygen.zip. Para reproduzir o processo em seus arquivos, será preciso reconfigurar o Doxygen de acordo com suas necessidades. Defina o caminho para o arquivo, o nome do projeto, preste atenção à codificação e linguagem.
• Preste atenção especial à aba Wizard, opção Output. Como formato para saída é usado plain html com a opção "With search function" marcada. Isso significa que o arquivo não será gerado no formato HtmlHelp. Se for selecionado "prepare fo compressed HTML (.chm)", não será desmarcada a opção "With search function", mas no final teremos uma nota sobre a impossibilidade de usar esta opção. Porém, nosso objetivo é obter ambas coisas.
• Portanto, a geração terá que ser executada duas vezes. Pela primeira vez, usando configurações simples do arquivo MQL5Doxygen.zip, obtemos documentação apenas no formato html na pasta de saída. A parte inicial da documentação está no arquivo index.html.
• Repetimos a geração alterando as configurações. Desmarcamos a opção "With search function". Marcamos "prepare fo compressed HTML (.chm)". Passamos para a aba Expert, opção HTML. Observe que deve ser definido CHM_FILE, isto é, nome do arquivo COM EXTENSÃO onde localizado o guia HtmlHlp, bem como o caminho acesso ao compilador hhc.exe em HHC_LOCATION. Se essas variáveis não forem inicializadas, o Doxygen preparará os arquivos de origem para o guia HtmlHlp, mas não conseguirá fazer o guia em si, e será preciso executar separadamente o HTML Help Workshop. Depois de fazer as alterações nas configurações, é possível começar a geração. Como resultado, obtemos documentação no formato html (como na primeira execução, mas sem pesquisa) e guia no formato HtmlHlp. Os resultados e o arquivo de configuração podem ser encontrados no arquivo anexado StandardLibrary.zip, onde removidos arquivos html desinteressantes. Quem ainda queira obter documentação de ajuda da biblioteca padrão no formato html agora pode fazer isso sozinho.

Continuamos com o seguinte exemplo. Desta vez, tentaremos marcar os arquivos com código através de tags e melhoraremos sua aparência.

• Primeiro, criaremos dois arquivos com um código de teste simples. Tentaremos dar-lhe uma certa "diversidade". Criaremos a folha de rosto mainpage.mq5 e, imediatamente, marcamo-la usando tags. Além disso, o colocaremos na folha de rosto uma imagem. Colocamos os três arquivos (exceto arquivos com imagem) na pasta que definiremos como "Source code directory", na aba Wizard, opção Project. Aqui definiremos a pasta para a saída e, se você quiser, o logotipo do projeto.
• Criaremos uma pasta para as imagens, e colocamo-las lá. Criaremos o arquivo footer.html editando o arquivo que o Doxygen utiliza para o "porão". O objetivo é remover a publicidade do próprio Doxygen. Os interessados podem adicionar aqui algo de sua autoria, mas se deve prestar atenção aos sinais de alerta no arquivo: "is needed for treeview function!", o que exige precisão. Fazemos alterações nas configurações, indicando onde está a imagem e o novo arquivo par o "porão". Para obter informações sobre como fazer isso, já mencionado acima.
• Criaremos um único arquivo com um exemplo de teste do uso desse código. Colocamo-lo numa pasta separada e especificamos o local onde o Doxygen deve procurá-lo.
• Agora que a estrutura do projeto está pronta, abrimos os arquivos com o código de teste e marcamos suas tags como lhe aprouver. Utilizamos o Sublime Text 3 com o conjunto definido de pacotes, referido no início deste artigo. No arquivo anexado, há uma das variantes de tal marcação, mas, obviamente, está longe de ser correta.
• Fazemos alterações finais nas configurações do Doxygen. Deve-se considerar a necessidade de realizar a saída em duas etapas, conforme descrito no exemplo anterior.
• Executamos a saída. Obtemos a documentação no formato HTML. Alteramos as configurações. Obtemos a documentação no formato HtmlHelp.

Todo o projeto, os arquivos de origem, o arquivo de configuração do Doxygen e a documentação final em ambos os formatos estão no arquivo anexado Custom_HTML_CHM.zip.

Conclusão

Neste artigo, eu queria evitar ao máximo a citação de documentação para vários programas e me concentrar nos momentos chave que prometem uma documentação de aparência espetacular. Para aqueles que querem saber mais sobre as tags e alternadores do Doxygen, anexo a documentação para o programa no formato CHM. Para os pacotes Sublime Texto 3 há uma documentação embutida, e é muito bem conhecida pelo editor.

Descrição dos arquivos anexados.

Nome	Descrição
Using_Doxygen_to_generate_Spanish_and_English_documentation.zip	Artigo em PDF
Doxygen_Manual.zip	Documentação em formato chm para o programa Doxygen
DoxyDoxygen.zip	Documentação em formato PDF para o pacote DoxyDoxygen
MQL5Doxygen.zip	Arquivo de configuração do Doxygen
StandardLibrary.zip	A documentação obtida em formato CHM
Custom_HTML_CHM.zip	Documentação obtida em formato html e CHM