Introducción

Cualquier desarrollador tarde o temprano se encuentra con la necesidad de crear documentación para su trabajo. La escritura de instrucciones y cualquier tipo de corrección es una parte indispensable de la actividad diaria y las relaciones con el cliente. Además, con el tiempo, se acumula una gran cantidad de bibliotecas y fragmentos de código, en ocasiones, de terceras personas. A la hora de aclararse entre tanto material, nos será de gran ayuda componer la documentación minuciosamente. Si al escribir el código tenemos en cuenta directamente la necesidad de desarrollar los materiales explicativos, el gasto de tiempo se reducirá a cero. Los comentarios y tags necesarios se inscriben simultáneamente con la creación del código. A primera vista, la ejecución de este trabajo no parece obligatoria, pero si se hace, esto ahorrará al desarrollador una gran cantidad de tiempo y nervios.

Vamos a analizar el proceso de creación de la documentación desde el principio hasta el final, deteniéndonos en los momentos principales. Ya se ha escrito con anterioridad un artículo sobre el tema, sin embargo, no toda la información expuesta en él es actual en estos momentos, y no todos los métodos funcionan. Vamos a intentar desarrollar y continuar el tema. Principalmente, analizaremos el trabajo con el programa Doxygen, usando Doxywizard.exe:

Añadimos archivos MQL a Doxygen

Bien, nuestro objetivo consistirá en  obtener un archivo de consulta / presentación sobre el código ya escrito, que se ubique en uno o varios archivos con una marca ya trazada. Como resultado, obtendremos un archivo  en el formato chm. Aparte de ello, crearemos archivos en formato html, que podrán cumplir por sí mismos tareas de presentación o consulta. Como ya hemos dicho, vamos a usar el programa Doxygen, que resulta conveniente para nuestro ojetivos.

La descripción del proceso de configuración del programa y la muestra de los archivos finales se ha expuesto en el artículo anteriormente mencionado, pero desde el momento de su publicación ha pasado mucho tiempo, y si ahora lo hacemos todo de la forma descrita en él, no conseguiremos nada. El programa funcionará, no habrá advertencias, ni mensajes de error, pero no se creará archivo alguno.

Por eso, lo primero que haremos es  resolver este problema introduciendo correcciones en la configuración del programa. Iniciamos doxywizard.exe y comenzamos la configuración, indicando el nombre del proyecto, la carpeta de entrada y salida, y marcando necesariamente "Optimize for C++ output" en el punto Mode de la pestaña Wizard.

Pasamos a la pestaña Expert y en el punto Input añadimos los archivos con la extensión necesaria:

Ahora Doxygen sabrá que necesita parsear los archivos con nuestras extensiones, ¡pero esto no es suficiente! Hay que indicar claramente al programa que los archivos con la extensión .mq* son un análogo de los archivos con la extensión .с, ejecutar la "representación" de la extensión (es probable que podamos llamar así a esta acción):

A partir de este momento, Doxygen comenzará el parseo de nuestros archivos y nos dará un resultado.

Codificación

Vamos a hablar de otro tipo de problemas que no ha sido suficientemente estudiado: los relacionados con la codificación de los documentos fuente y los documentos finales.

Si el idioma de la documentación es el inglés, entonces no habrá ningún problema. Sin embargo, si queremos crear la documentación en otro idioma, veremos símbolos ilegibles. El motivo es que por defecto se considera que todos los documentos son creados en la codificación UTF-8. Si la parte factual de los documentos tiene otra codificación, el texto no será legible. Vamos a ver la solución:

1. Decidimos el idioma y la codificación por defecto. Serán UTF-8 y el idioma ruso:
   

   
   

   
   

   
   

   
   

   Hay que notar que no hemos logrado aún realizar el cambio DOXYFILE_ENCODING. Sea cual sea la codificación que se defina en este campo de edición, en realidad se definirá UTF-8. Lo más probable es que solo se pueda cambiar de una forma la codificación en este lugar, escribiéndola explícitamente en el archivo, con el que sustituiremos después "Head" por defecto (esto lo hemos visto más arriba). Sin embargo, de esta forma, difícilmente podremos lograr el resultado deseado.
   

2. Hay que indicar la codificación en la que se crean los documentos fuente, ya que no necesariamente será UTF-8. En nuestro caso, seguramente será la codificación CP1251. Si una parte de los documentos se ha creado en una codificación, y otra parte en otra, recodificaremos los archivos de tal forma que para todos los documentos fuente solo haya una codificación, y la escribiremos en este campo de edición:
   

   
   

   
   

   
   

3. Y, por supuesto, si se supone la realización de la muestra en el formato del manual CHM, deberemos indicar explícitamente qué codificación se usa en el índice HtmlHelp (archivo con la extensión hhk):
   

   
   

   
   

   
   

   Quien quiera conocer información más detallada sobre esta cuestión, podrá consultar el archivo que adjuntamos, que trata la creación de documentación en español e inglés usando Doxygen.

Ahora vamos a detenernos en momentos más generales y que son más importantes, en particular, en el aspecto externo del archivo html generado.

El encabezamiento y el pie de la página

Las opciones disponibles están ubicadas en la pestaña Expert, en el punto HTML. Obviamente, resultan útiles los conmutadores que permiten conectar a la creación de la documentación final los archivos html personalizados, los campos HTML_HEADER, HTML_FOOTER y HTML_STYLESHEET. Mirando el nombre de los campos se puede entender de qué es responsable cada uno de ellos, del encabezamiento en cada página, del pie de página o de los estilos de representación. Recordemos: para que los archivos html se generen, se debe marcar el conmutador GENERATE_HTML en esta pestaña.

Ambos archivos html analizados se escriben según normas especiales, aunque para el archivo footer.html sencillamente se nos ha activado un fragmento de texto html sin ningún encabezamiento, solo con esta forma:

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

Pero lo mejor es respetar las reglas. Para comprender cómo precisamente pueden construirse los archivos de usuario, podemos generar aquellos usados por defecto por el programa. Obtendremos no solo los dos archivos html buscados, sino también un recuadro de estilos. Lo haremos con este comando:

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

Aquí tenemos un fragmento del archivo 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>

Saltan a la vista de inmediato los numerosos marcadores de posición (placeholders), cuyo nombre y cometido está disponible en la documentación. Se puede comprender con facilidad dónde precisamente se muestra el anuncio del propio Doxygen, y dónde se pueden poner sus enlaces. De forma análoga se podrá corregir también new_header.html, y si lo desea, el recuadro de estilos, pudiendo incluirlos de forma consecutiva en la pestaña indicada. De esta forma, es posible cambiar de forma sustancial el aspecto externo de la documentación en función de nuestros propias intenciones.

Procesamiento de preprocesador

Doxygen permite procesar los archivos de forma preliminar. Esto se hace para dar la posibilidad al programa de procesar los macros del tipo BEGIN_MESSAGE_MAP y las construcciones del tipo __declspec de Visual Studio. Para nuestros scripts esto no es tan actual, por eso simplemente mencionaremos aquí esta posibilidad, sin profundizar en detalles. Este mecanismo se ajusta en el punto Preprocessor de la pestaña Expert. Asimismo, destacaremos la posibilidad de crear filtros cuyo objetivo sea transformar el archivo de entrada de tal forma que lo pueda entender Doxygen. Este filtro constituye un programa de consola externo, en cuya línea de comandos se añade el nombre del archivo procesado. El propio programa-filtro supone básicamente un conjunto de expresiones regulares que transforman, por ejemplo, un programa en un ensamblador que sea comprensible para Doxygen. El desarrollador debe decidir si le conviene usar el procesamiento de preprocesador. Con la ayuda de este mecanismo, podemos, por ejemplo, hacer comprensible para Doxygen la construcción #property.

Inclusión de ejemplos

Es muy interesante la posibilidad de incluir ejemplos en la documentación. No es algo obligatorio, pero da a la documentación un aspecto más redondo y profesional. Los ejemplos se incluyen en el proyecto en forma de uno o varios archivos. Para ello, en la página con el código al que el desarrollador querría añadir el ejemplo, deberá ubicarse esta construcción:

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

Aquí se define el nombre del archivo con el ejemplo. En la segunda línea se pueden enumerar las funciones o clases a ilustarar con ejemplos. Pero esto no es suficiente: aún desconocemos el lugar donde se ubica el archivo. La ruta a los archivos con ejemplos se debe indicar explícitamente en Doxygen. Esto se hace de la forma mostrada en la imagen:  indicamos la ruta a los archivos y los patrones de sus nombres:

Añadiendo varias rutas y usando la bandera EXAMPLE_RECURSIVE, podemos incluir en nuestra documentación multitud de archivos con ejemplos, obteniendo como resultado un manual avanzado.

Tags HTML

Otro recurso útil de Doxygen es el trabajo con fragmentos de la marca html, que se puede ubicar directamente en los bloques de los comentarios. En la documentación existe una lista magnífica de tags html, que Doxygen podrá procesar e insertar en el documento final. Por ejemplo, este texto se inserta en la descrpción del macros y el recuadro con el encabezamiento:

/*!
  \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"

Junto con la marca html se pueden usar pseudo-símbolos del tipo  

Al usar los enlaces, existe una particularidad más: Automatic link generation. En la práctica, esto significa que Doxygen transformará un texto del tipo https://www.mql5.com en el enlace correcto y lo insertará en el documento final. Automatic link generation no se limita a esa transformación. Se pueden crear enlaces a artículos, clases, funciones aparte. Esto vendrá bien a la hora de crear los apartados de la documentación del tipo "See Also". En general, esta marca permite describir aún mejor el fragmento necesario de código; usar para la marca del tipo "Prev/Next" y formas más desarrolladas de paginación puede ser adecuado para el posicionamiento en buscadores y los anuncios.

Página de título

Hemos hablado más arriba de la posibilidad de sustituir el código del encabezamiento y en el pie de página de las páginas web por los nuestros. Aparte de esto, el desarrollador tiene la posibilidad de elaborar un diseño aparte para la página de título. Para ello, debe indicar en uno de los archivos que el contenido es la página de título. Esto se hace con la ayuda del tag \mainpage, incluido al inicio de la página:

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

En esta marca se declara que el archivo en el que se encuentra es la página de título con el encabezamiento "My Personal Index Page", después de la cual se insertará la imagen "i.jpg". La imagen debe prepararse de antemano, y la ruta hacia ella debe ser conocida para Doxygen:

Aparte de las imágenes, se pueden insertar archivos y otros tipos.

Muestra en los formatos html y HtmlHelp

Es posible crear documentación en varios formatos. En la pestaña Wizard en el punto Output se pueden marcar los necesarios. Primero va la creación de documentación en html normal. En la carpeta que se ha indicado como carpeta de salida, se creará el archivo index.html. Este será el archivo principal de toda la documentación. Sin embargo, este formato no siempre es cómodo. Por eso, analizaremos la creación en el formato HtmlHelp. Para ello, hay que marcar el conmutador HTML y "prepare for compressed HTML" en el mismo lugar y en la misma pestaña. Aparte, en la pestaña Expert en el punto HTML en el campo de edición CHM_FILE indicaremos el nombre del archivo HtmlHelp del manual con la extensión correspondiente, y en el campo inferior (HHC_LOCATION), la ruta al compilador del manual hhc.exe está disponible. No se trata de un parámetro obligatorio. Si el campo se queda vacío, se prepararán todos los archivos necesarios, y el manual en el formato chm se deberá obtener con una llamada aparte del programa HTML Help Workshop.

Asimismo, hay otros conmutadores adicionales para realizar un ajuste más preciso. Es recomendable prestar especial atención a GENERATE_CHI. Por defecto, el estado de este conmutador está reseteado, a cero. Pero si lo configuramos, Doxygen generará un archivo de índice aparte con la extensión CHI. Si eliminamos el archivo como consecuencia de ello, el uso del archivo principal del manual se verá muy dificultado. Prácticamente todo el manual en formato HtmlHlp perderá una gran parte de su funcionalidad.

Ya hemos hablado sobre la configuración de la codificación. Solo queda pasar a la pestaña Run y pulsar el botón "Run Doxygen". Tras pasar una página completa de mensajes técnicos, Doxygen anunciará la finalización del trabajo. En la parte baja está el botón "Show HTML output", para ver la documentación en el navegador. Deberemos localizar el archivo en formato HtmlHelp e iniciarlo manualmente.

Un pequeño vídeo sobre el trabajo con Doxywizard:

A continuación, analizaremos varios momentos secundarios pero interesantes.

Posibilidades del editor Sublime Text 3 para la ubicación de tags en el código en MQL5

Para que Doxygen funcione, es necesario ubicar tags especiales en el texto del programa documentado. Se colocan los tags en comentarios de una o varias líneas hechos a diferentes segmentos de código, clases, macros, funciones, etcétera. Cuanta más información quiera transmitir el desarrollador en la documentación elaborada, y más cuidado muestre al estructurarla, más compleja resultará la estructura de los tags.

En cuanto a la colocación de los tags, se debe realizar en el editor MT5. Además, habrá que vigilar atentamente los errores que puedan aparecer. Podemos simplificar un poco este proceso y automatizarlo parcialemente. Usaremos el editor Sublime Text 3. Este reconoce MQL4, y por consiguiente, puede trabajar con MQL5. Conectamos al editor ambos paquetes relacionados con MQL.

Después instalamos el paquete que sea capaz de trabajar con la marca DoxyDoxygen que necesitemos. En él hay atajos de teclado y es capaz de traducir diferentes idiomas y de autocompletar. Este paquete le ayudará con mayor rapidez y menor esfuerzo a colocar correctamente todos los tags necesarios. Como se ha escrito en la documentación (se puede encontrar en los archivos anexos), después de finalizar el marcado, podremos llamar a Doxygen directamente desde el editor. Allí mismo, en la documentación adjunta, podrá encontrar la descripción del proceso de configuración del paquete.

En general, no hay cuestiones especiales, ni tampoco sutilezas en el funcionamiento del paquete, por eso no vamos a deternos con detalle en él.

Muestra de los formatos pdf y djvu

En Doxygen se contempla esta interesante posibilidad, pero a día de hoy, no se han finalizado los trabajos de implemetación de la misma. Podemos intentar ya mostrar la documentación en estos formatos, hay cierta información disponible en la documentación de Doxygen, y también existen algunos artículos e instrucciones en otras páginas. Aquí analizaremos la muestra en el formato pdf con un poco más de detalle.

1. En la pestaña Wizard en el punto Output habrá que marcar la muestra en el formato LaTeX y elegir el formato "for PDF". En la documentación se escribe que hay que marcar GENERATE_PERLMODE en la pestaña Expert en el punto PerlMod, pero nos saltaremos este paso.
2. Realizamos otros ajustes necesarios, incluida la muestra en los formatos CHM y html (si así se requiere).
3. Creamos los documentos necesarios.

En la carpeta de salida, se creará la carpeta latex, donde se ubicarán los archivos de este formato. Con ello, ya hemos terminado el trabajo con Doxygen. Ahora tenemos que transformar los archivos del formato latex al formato PDF. Hemos usado el programa MikTex, tomado de aquí en la forma portable. Instalamos e iniciamos el programa. Elegimos en él TeXworks. En la ventana del editor buscamos y abrimos el archivo refman.tex, que ha creado para nosotros Doxygen en la carpeta latex. Después, en el panel de instrumentos del editor en la lista combinada elegimos XeLaTex y pulsamos el botón grande y verde de la izquierda. Observamos una serie de mensajes de diagnóstico. Durante el funcionamiento nos propondrán instalar paquetes adicionales (hay que aceptar). Si el código ha finalizado con error, podremos intentar repetir la "compilación".

Como resultado, en la misma carpeta latex se creará el  archivo refman.pdf con nuestra documentación. La calidad de la muestra deja bastante que desear: resulta obvio que tendremos que editar la disposición de forma adicional. Posiblemente se podrían evitar muchos defectos editando los archivos fuente de latex. Sin embargo, no debemos olvidar que el trabajo de implementación de esta posibilidad no se ha finalizado, por eso esperaremos la inclusión oficial de la opción en Doxygen.

Uso práctico

Vamos a ver ejemplos concretos y mostrar cómo se pueden usar Doxygen y otros programas para crear documentación. Comenzaremos creando la documentación para la biblioteca estándar: un conjunto de clases en \MQL5\Include. Utilizaremos un método sencillo: pasaremos por todos los archivos el programaDoxyGen, sin colocar tags adicionales en los propios archivos. Esto nos dará la posibilidad de obtener información adicional importante sobre los elementos de las bibliotecas, pero veremos qué podemos obtener precisamente. Es posible que nos venga bien el resultado obtenido. Para comenzar, supongamos que todos los componentes programáticos necesarios ya han sido instalados en la computadora. Bien, vamos a comenzar:

En cualquier caso, vamos a curarnos en salud y copiar la biblioteca estándar en cualquier carpeta. Durante el funcionamiento no se presupone que haya cualquier tipo de grabación en el archivo, pero mejor no arriesgarse.

• Iniciamos Doxygen y comenzamos a configurarlo. Para llevar a cabo el ajuste preliminar, podemos usar el archivo adjunto MQL5Doxygen.zip. Para reproducir el proceso en nuestros archivos, es necesario reconfigurar Doxygen según nuestras necesidades. Indique sus rutas para los archivos y su nombre de proyecto, prestando atención a la codificación y al idioma.
  
• Preste especial atención a la pestaña Wizard, punto Output. Como formato para la muestra se usa plain html, con el punto "With search function" marcado. Esto significa que el archivo en el formato HtmlHelp no será generado. Si elegimos "prepare fo compressed HTML (.chm)", desde el punto "With search function" la marca no se quitará, sin embargo, al final recibiremos una advertencia sobre la imposibilidad de usar este punto. Nuestro objetivo es lograr lo uno y lo otro.
  
• Por eso tendremos que realizar el proceso de generación dos veces. La primera vez, lo haremos utilizando los ajustes sencillos del archivo MQL5Doxygen.zip, obteniendo la documentación solo en el formato html en la carpeta asignada para la muestra. El comienzo de toda la documentación se encuentra en el archivo index.html.
  
• Repetimos la generación, cambiando los ajustes. Quitamos la marca del punto "With search function". Marcamos  "prepare fo compressed HTML (.chm)". Pasamos a la pestaña Expert, punto HTML. Prestemos atención a que se deberá indicar CHM_FILE:  el nombre del archivo CON EXTENSIÓN en el que estará el manual HtmlHlp, así como la ruta de acceso al compilador hhc.exe  en HHC_LOCATION. Si estas variables no se inicializan, Doxygen preparará los archivos fuente para el manual HtmlHlp, pero no podrá crear el propio manual, y HTML Help Workshop se deberá iniciar por separado. Después de introducir los cambios en los ajustes, podemos comenzar la generación. Como resultado, obtendremos la documentación en el formato html (como en la primera pasada, pero sin búsqueda) y el manual en el formato HtmlHlp. Podrá encontrar los resultados del funcionamiento y el archivo de configuración en el anexo StandardLibrary.zip, del que se han quitado los archivos del formato html, que no nos interesan. Aquellos que de todas formas deseen obtener información de ayuda para la biblioteca estándar en el formato html, ahora podrán hacerlo de forma independiente.
  

Continuamos con el siguiente ejemplo. Esta vez intentaremos marcar con tags los archivos con código y mejorar su aspecto externo.

• Para comenzar, crearemos dos archivos con un sencillísimo código de prueba. Vamos a tratar de transmitirle cierta "diversidad". Creamos la página de título mainpage.mq5, que marcamos inmediatamente con los tags necesarios. Además, colocamos en la página de título una imagen. Los tres archivos (excepto el archivo con la imagen) los colocamos en una carpeta que definiremos como "Source code directory" en la pestaña Wizard en el punto Project. Aquí mismo definiremos la carpeta para la muestra o, si así lo queremos, el logotipo del proyecto.
• Creamos una carpeta para la imagen y la ubicamos ahí. Creamos el archivo footer.html editando el archivo que Doxygen usa para el pie de página. El objetivo es quitar el anuncio del propio Doxygen. Quien así lo desee, podrá añadir aquí algo de su cosecha, pero nosotros hemos prestado atención al rótulo de advertencia: "is needed for treeview function!", que nos sugiere tener cuidado. Introducimos los cambios en los ajustes, indicando dónde se encuentra la imagen y el nuevo archivo para el pie de página. Ya hemos mencionado más arriba cómo hacer esto.
• Creamos un archivo con el ejemplo de prueba del uso de este código. Lo ubicamos en una carpeta aparte e indicamos a Doxygen dónde buscarlo.
  
• Ahora que hemos creado la estructura, abrimos los archivos con el código de prueba y los marcamos con tags de la forma que consideremos necesaria. Usamos Sublime Text 3 con el número de paquetes indicado al inicio del artículo. En el archivo adjunto estará una de las variantes de esta marca, pero es obvio que no será la única correcta.
• Introducimos los cambios definitivos en los ajustes de Doxygen. Hay que tener en cuenta que podría ser necesario ejecutar la muestra en dos etapas, como se describe en el ejemplo pasado.
  
• Realizamos la muestra. Obtenemos la documentación en formato HTML. Cambiamos los ajustes. Obtenemos la documentación en formato HtmlHelp.

El proyecto completo, los archivos fuente, el archivo de ajustes de Doxygen y la documentación final en ambos formatos están en el archivo adjunto Custom_HTML_CHM.zip.

Conclusión

En este artículo queríamos adoptar un enfoque que evitara al máximo citar la documentación de diferentes programas, para concentrarnos en los momentos complicados, insinuados por el efectista aspecto externo de la documentación. Para aquellos que quieran familiarizarse al máximo con todos los tags y el conmutador Doxygen, adjuntamos la documentación del programa en el formato CHM. Para los paquetes  Sublime Text 3 existe documentación incorporada; el propio editor nos es bien conocido.

Descripción de los archivos adjuntos.

Nombre	Descripción
Using_Doxygen_to_generate_Spanish_and_English_documentation.zip	Artículo en el formato pdf
Doxygen_Manual.zip	Documentación en formato chm del programa Doxygen
DoxyDoxygen.zip	Documentación en formato pdf del paquete DoxyDoxygen
MQL5Doxygen.zip	Archivo de configuración de Doxygen
StandardLibrary.zip	Documentación obtenida en el formato CHM
Custom_HTML_CHM.zip	Documentación obtenida en el formato html y CHM