Documentación generada automáticamente para el código de MQL5

1. Introducción

La mayoría de desarrolladores de código Java estarán familiarizados con la documentación generada automáticamente que puede obtenerse con JavaDocs. La idea es añadir comentarios al código de forma semiestructurada para que pueda ser extraída en forma de archivo de ayuda por el que sea fácil navegar.

El mundo de C++ tiene también una serie de autogeneradores de documentación, siendo líderes SandCastle y Doxygen, ambos de Microsoft. He decidido ver qué tal puede Doxygen generar documentación en MQL5, que es en esencia un subconjunto personalizado de C++. Para mí, este es un paso importante en la madurez de MQL5, ya que la complejidad del lenguaje es capaz de mejorar fácilmente algunas librerías de clases muy grandes.

El experimento funcionó muy bien y creo que la documentación de ayuda que ofrece Doxygen a partir del código MQL5 añadirá una gran cantidad de valor a este.

2. Doxygen

Doxygen es un generador de documentación automático de código abierto disponible bajo licencia GNU GPL, lo que significa que su desarrollo ha sido similar a otros proyectos de código abierto como Linux o Mozilla. Doxygen puede descargarse y usarse de forma gratuita, su código fuente es abierto para que cualquier persona puede acceder a él y ha sido desarrollado y está siendo mejorado mediante la colaboración entre una serie de desarrolladores que donan su tiempo.

En su nivel de uso más básico, Doxygen simplemente analiza todo el código C++ (o MQL5) en un proyecto y muestra su estructura en un archivo de ayuda por el que resulta fácil navegar. Esto es particularmente útil con el código orientado a objeto, que tiende a tener una jerarquía de clases extensiva y un gran número de funciones de miembros. Para utilizar al completo las características de Doxygen, los comentarios estructurados deben también ser escritos en el código para que Doxygen pueda leerlos y añadir información en el archivo de ayuda generado.

2.1 Descargar Doxygen

La página de inicio de Doxygen es http://www.doxygen.org/. Desde aquí puede navegar hasta la página de descarga y descargar la última versión para Windows. En el momento en el que escribo este artículo la versión disponible es doxygen-1.6.1, ver a continuación:

Figura 1. Descarga de Doxygen

2.2 Configurar y ejecutar Doxygen

Es poco lo que se requiere hacer, excepto añadir los tipos de archivo *.mqh y *.mq5 y poner en marcha la generación de la ayuda HTML. Las siguientes cinco figuras se ejecutan a través de la configuración.

Las primeras cuatro capturas de pantalla (Figuras 2 a 5) se ejecutan a través de las pantallas del Wizard:

Figura 2. Configurar Doxygen - Wizard 1

Figura 3. Configurar Doxygen - Wizard 2

Figura 4. Configurar Doxygen - Wizard 3

Figura 5. Configurar Doxygen - Wizard 4

Por último, hay un cambio de nivel experto para añadir los tipos de archivo mqh y mq5:

Figura 6. Configurar Doxygen - incluir archivos mqh y mq5 files

Y ya está listo para ejecutarse. Tenga en cuenta que Doxygen almacenará y leerá datos en un archivo de configuración que está incluido en el zip adjunto a este artículo.

Figura 7. Ejecutar Doxygen

2.3 Usar Doxygen

Doxygen tiene un excelente archivo de ayuda html compilado (construido, por supuesto, con Doxygen, aquí está la versión html original) que contiene una increíble matriz de características de documentación con una representación perfecta de fórmulas matemáticas complejas. No obstante, la herramienta puede también usarse eficazmente de forma muy sencilla para crear archivos de ayuda.

Este es un ejemplo de la función CiMACD::Create() en MQL5/Include/Oscilators.mqh. Observe que estos archivos de indicador no eran originariamente parte de la anterior distribución beta y puede que necesitemos volver a descargar Meta Trader 5 para verlos.

//+------------------------------------------------------------------+
//| 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)

Algunos simples cambios en las palabras clave preparan los comentarios para su interpretación por Doxygen. Los comentarios son ahora con triple barra (///), INPUT: se ha cambiado por \param, y OUTPUT: por \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)

Y luego cuando Doxygen lo ha procesado, el archivo de ayuda tiene el aspecto de la Figura 8:

Figura 8. CiMACD::Create() como se ve en el archivo HTML generado por Doxygen

2.4 Usar Doxygen en todo el conjunto de códigos de MQL5

Donde Doxygen es más potente en la creación de un archivo de ayuda para proyectos grandes. En la distribución de Meta Trader 5, en la carpeta MQL5 se encuentran más de un centenar de archivos .mq5 y mqh, muchos de los cuales están interrelacionados.

He escrito un script MetaquotesCommentsToDoxygen.mq5 (incluido en el archivo zip adjunto) que realiza las conversiones de comentarios de Metaquotes a Doxygen mencionadas antes. Este no es un paso esencial para generar un archivo de ayuda, pero muestra la utilidad de las características de documentación adicionales de Doxygen.

El procedimiento que he utilizado para producir un archivo de ayuda de la codificación de caracteres de MQL5 es el siguiente

• Copiamos la carpeta MQL5 y subcarpetas en MQL5/files
• Eliminamos MQL5/files/MQL5/Include/Strings/string.mqh. Por razones desconocidas este archivo evita que Doxygen complete el análisis de su código.

Opciones para la documentación adicional a partir de los comentarios estructurados:

• En la carpeta MQL5/Files folder, ejecutamos el comando de Windows/DOS xcopy *.mq* c:\ /S/L > MQL5codeList.txt
• Ejecutamos el script MetaquotesCommentsToDoxygen.mq5 en cualquier gráfico

La documentación de ayuda obtenida es de buena calidad y muestra rápidamente su utilidad. Las Figuras 9 a 12 son un ejemplo de lo que puede ver

Figura 9. Lista de clase generada por Doxygen

Figura 10. Diagrama de árbol de la clase generada por Doxygen para CArrayObj

Figura 11. Lista de funciones miembro generadas por Doxygen para CArrayObj

Figura 12. Lista Defines generada por Doxygen

3. Taller de ayuda HTML de Microsoft

Hay un paso más necesario para que el resultado de Doxygen sea aún más útil. Doxygen produce un archivo index.html que apunta a un gran número de otros archivos html e imágenes. Es en esencia un pequeño sitio web y por tanto muy farragoso a la hora de distribuirlo.

Hace tiempo, Microsoft reconoció que los archivos de ayuda para las aplicaciones de Windows debían ser escritos en html, por lo que desarrollaron con esta finalidad su Taller de ayuda de HTML. El taller de ayuda de HTML usa un conjunto de archivos similares al resultado de Doxygen y los compila en un único archivo .chm. Este es el mismo formato que los archivos de ayuda distribuidos con Meta Trader 5.

3.1 Descargar el Taller de ayuda de HTML

Puede descargar e instalar htmlhelp.exe desde la página de Microsoft aquí.

Figura 13. Descargar la ayuda HTML

3.2 Crear un archivo de ayuda HTML compilado

El resultado del trabajo de Doxygen puede convertirse fácilmente en un archivo de ayuda html compilado a través del taller de ayuda de HTML. Tal y como se ha configurado para este artículo, Doxygen produce un archivo indez.hhp listo para que sea abierto por el taller de ayuda de HTML como se muestra en la Figura 14.

Figura 14. Ubicación del archivo index.hhp generado por Doxygen

 El siguiente paso es compilar:

Figura 15. Compilar con la ayuda HTML

... y cuando ha finalizado, el nuevo archivo index.chm puede copiarse en la carpeta MetaTrader 5/Help y ser renombrado, como se muestra en las figuras 16 y 17 a continuación.

Figura 16. ubicación de index.chm

Figure 17. index.chm copiado a la carpeta de ayuda y renombrado

4. Resumen

Este ejercicio me ha convencido para usar Doxygen o un equivalente en el futuro a la hora de documentar cualquier código MQL5 que quiera que la gente utilice y comprenda, y espero que otros hagan lo mismo.

Apéndice. Descripción de los archivos de Doxygen adjuntos en files.zip

Archivo	Descripción	Copiar a
Codificación de caracteres de MQL5 help.chm	Archivo de ayuda HTML compilado de todo el código distribuido con Meta Trader 5 build 229, 8 de diciembre de 2009.	MetaTrader 5/Help
MetaquotesCommentsToDoxygen.mq5	Script que modifica los comentarios en el código MQL5 para que Doxygen pueda interpretarlos	MQL5/Scripts
MQL5codeList.txt	Una lista de todos los archivos MQL5 distribuidos	MQL5/Files
MQL5_Doxygen	Archivo de configuración de Doxygen	MQL5