You are currently browsing the tag archive for the ‘doxygen’ tag.

La primera tarea del sistema de documentación automatizado doxygen es la creación de un manual de referencia del código del programa. Sin embargo, doxygen ofrece también la funcionalidad de añadir un texto libre. Por la capacidad de doxygen de entender etiquetas de HTML, podemos editar un documento HTML con un editor aparte y luego integrarlo en la documentación generada con doxygen. Esto nos trae la ventaja de poder entregar una documentación completa y actualizada con cada ejecución de doxygen.

Creación de documentación libre

Doxygen conoce varias etiquetas para la creación de documentación libre. En primer lugar están las etiquetas \mainpage, \page y \subpage para la creación y la estructuración de páginas independientes. Dentro de cada página podemos estructurar el texto en apartados con las etiquetas provenientes LaTeX: \section, \subsection, \subsubsection y \paragraph. Conviene guardar la documentación libre en un fichero aparte por no tener correspondencia a ninguna entidad de código en concreto. El sufijo previsto para estos ficheros es dox, es decir, podemos crear una carpeta “doc” o “dox” que incluye todos los ficheros fuente que contienen documentación pero ninguna línea de código ejecutable.

Las etiquetas mencionadas arriba deben encontrarse dentro de un comentario de documentación. Lo más conveniente en este caso es abrir el comentario con /** o /*! en la primera línea y cerrarlo con */ en la última. Doxygen no exige iniciar una línea en medio con *. Ver la documentación de doxygen para un ejemplo.

Lo normal sería escribir la documentación libre en un fichero de texto, pero como ya he mencionado, en este artículo queremos averiguar, si podemos utilizar fuentes escritos en HTML. Dentro de lo que cabe tenemos dos estrategias para usarlas:

  1. Crear un documento HTML que doxygen lee y interpreta como un fichero fuente, es decir, un fichero .dox, y
  2. integrar un documento HTML externo

Ambas maneras tienen ventajas y desventajas que detallaremos a continuación.

Procesar HTML como fichero fuente

Podemos crear un fichero HTML y dejarlo procesar por doxygen como si fuera un fichero fuente. Doxygen entiende la mayoría de las etiquetas de HTML. Las que no entiende son en primer lugar etiquetas de contenido dinámico como OBJECT o EMBED. Esto no es de extrañar ya que doxygen no es un navegador de Internet sino una herramienta de documentación. Lo que duele más que tampoco entiende las etiquetas de cabecera. A contrario de lo que diga la documentación, la versión 1.7.1 que yo probé, no reconoce nada de lo que aparece entre <HEAD> y </HEAD> y tampoco la etiqueta BODY. Estas etiquetas aparecen entonces como cualquier texto normal.

Doxygen tampoco reconoce el comentario de HTML <– –>. Por lo tanto no podríamos esconder la apertura del comentario de documentación /** dentro de un comentario para que no nos aparezca si abrimos el fichero HTML en un navegador. En fin, no es posible crear un documento HTML que queda perfecto tanto en un navegador y en el resultado de doxygen a la vez. Todavía necesitamos un poco de trabajo manual:

Creamos un fichero dox que contiene algo como lo siguiente

/** \page mi_pagina_html Mi página en HTML
<h1>Soy un título</h1>
<p>En esta página podemos hablar de asuntos <em>muy</em> importantes.</p>
*/

Entre la primera y la última línea copiamos todo lo que se encuentra entre las etiquetas <BODY> y </BODY> en el documento HTML. (En este caso sólo he puesto dos líneas.)

La ventaja de esta manera es que doxygen crea una salida homogénea con las otras partes de la documentación. Más interesante aún es que doxygen enlaza los nombres de identificadores con la referencia correspondiente. De esta manera podemos, por ejemplo, crear un manual de usuario de una biblioteca en que aparecen automáticamente las enlaces al manual de referencia de los objetos de que estamos hablando.

Incluir un documento HTML

A veces los documentos HTML no son tan simples para que podamos usarlo directamente con doxygen. Puede haber varias razones. Por ejemplo:

  • El documento HTML se quiere usar tal cual como una página de Internet.
  • El documento usa una hoja de estilo u otros enlaces. En este caso y el anterior no podemos quitar la cabecera.
  • El documento usa contenido dinámico con Javascript.
  • El documento usa contenido empotrado como vídeos o animaciones flash.

En todos estos casos no queremos perder las características del propio HTML. Lo que podemos hacer es crear un pequeño fichero dox con el contenido siguiente:

/** \page mi_otra_pagina_html Mi otra página HTML
\htmlinclude "mi_fichero.html"
(Este documento sólo está disponible en la versión HTML de la documentación.)
*/

Con esta fuente, doxygen crea una página en que incluye el documento HTML “mi_fichero.html”, pero sólo para la versión HTML de la documentación. Desgraciadamente no existe una etiqueta en doxygen, con que podemos escribir algo en todos los formatos menos HTML. Así aparece una página prácticamente vacía en los demás formatos. Sólo se ve la frase “(Este documento sólo está disponible en la versión HTML de la documentación.)“. Esta frase aparece también al final del documento HTML, pero visualmente se impone menos. Existen también comandos exclusivos para otros formatos como \latexonly, pero no podrán sustituir el contenido dinámico de una página HTML, desde luego.

Debemos añadir el directorio, donde guardamos los ficheros HTML a incluir, al EXAMPLE_PATH de la configuración de doxygen. Si no es posible que doxygen no encuentra los ficheros que incluimos.

La ventaja de incluir un documento HTML de esta manera es poder usarlo sin modificación y aprovecharse de toda la potencia que una página WEB ofrece. La desventaja es que doxygen no enlaza nombres de identificadores con el manual de referencia y en los formatos no HTML no aparece ningún su contenido. Sin embargo, en muchos casos esto no supone un problema, ya que no se crea una documentación en otro formato que HTML.

Una aplicación de este truco puede ser la inclusión de un manual de usuario u otro texto libre. Se puede escribir en un editor como Microsoft Word y guardarlo como una página HTML. Luego se incluye esta página mediante \htmlinclude en la documentación de doxygen. Así es posible mantener una documentación completa y actualizada en todo momento.

Una cosa que, por cierto, no funciona es usar el comando \link a un fichero interno para crear un enlace a este documento HTML en la documentación. El enlace, sí, estará en la documentación creada por doxygen, pero no el fichero que enlaza. Esto sólo se puede hacer para documentos con una URL de Internet pública.

Conclusión

Hemos visto dos maneras de incluir documentación adicional al manual de referencia que doxygen crea a partir del código. La capacidad de doxygen de interpretar muchas etiquetas HTML permite incluir documentos escritos en HTML en la documentación. Es una buena opción para documentos no interactivos. Para páginas HTML más complejos se ofrece incluir la página tal cual mediante \htmlinclude, que mantiene toda la potencia de una página interactiva, pero a coste de no poder verlo en los demás formatos que doxygen puede crear.

Referencias

Anuncios

Doxygen es una herramienta de documentación automatizada muy potente. Como muchos programas viene con la configuración para el inglés americano por defecto. Por eso puede haber problemas a la hora de procesar bien comentarios que usan letras con acentos como suele haber en español y muchos otros idiomas.

Una solución al problema es guardar los ficheros con la codificación UTF-8, que es la que viene por defecto también en phpDocumentor. Sin embargo, doxygen permite especificar explícitamente qué codificación a usar.

Si usas el interfaz gráfico Docwizard, entonces puedes pinchar en la pestaña “Expert”, y luego en el menú de los “Topics” seleccionas “Input”. A la derecha hay un campo que se llama INPUT_ENCODING. Cambia el valor (“UTF-8” por defecto) a la codificación de tus ficheros fuente. Para el español suele ser la codificación ISO-8859-1. Obviamente sólo puedes usar una codificación de caracteres para un proyecto.

Si no usas el interfaz gráfico puedes buscar por la cadena de texto INPUT_ENCODING en el fichero de configuración.

Si no estás seguro qué codificación a elegir, entonces puedes visualizar la documentación generada y jugar con la codificación de los caracteres del navegador hasta tu documentación  salga bien. La codificación puedes cambiar (en Mozilla Firefox) con el menú View (Ver) -> Character Encoding. Cuando haces estas pruebas fíjate en los textos que has escrito tú en la documentación; y no en los títulos que añade doxygen. Cuando pones la codificación correcta en el campo INPUT_ENCODING, tanto los textos generados a partir de los comentarios como los que añade doxygen saldrán con los acentos bien. Recuerda volver poner tu navegador a autodetectar la codificación.

Por cierto, también se puede modificar la codificación del fichero de configuración de doxygen. En la pestaña “Expert” seleccionas en el menú “Topics” el punto “Project”. A la derecha hay un campo que se llama DOXYFILE_ENCODING. Cambia el valor (“UTF-8” por defecto) a la codificación desdeada.

Referencias

En muchas ocasiones se pide un manual de referencia del código. Esto es especialmente importante a la hora de crear una librería que esté ideada para que otro programador la use en una aplicación final. Este manual engloba de alguna forma un trabajo doble: hay que explicar bien el funcionamiento de cada función en el código mismo y luego repetir la misma información en un documento de texto.

De este trabajo pueden encargarse sistemas de documentación automáticos. Leen el código y extraen la información necesaria para generar la documentación. Muchas veces permiten varios tipos de documentos de salida: en formato HTML, en formato PDF, como fichero de HTML comprimida (CHM) o en formato “Rich Text”.

Probablemente el más influyente de estos sistemas es javadoc. Fue incluido en el entorno Java de Sun como una parte integral del sistema y ha marcado desde entonces el formato de los comentarios de documentación. El programa de más uso es probablemente doxygen, ya que puede entender la sintaxis de muchos lenguajes, muy especialmente de C++. Para PHP es recomendable usar phpDocumentor.

A todos estos sistemas es común que requieren un marcador especial para los comentarios que se exportan del código a la documentación final. El más extendido es el de javadoc que marca los comentarios entre /** y */. Nota que es nada más que un comentario al estilo /**/ donde la primera letra es un asterisco. Sin embargo, para el sistema de documentación, el segundo asterisco en /** lo marca como un comentario de documentación cuyo contenido será procesado por el sistema de documentación automatizado.

Dentro de este bloque están permitido una multitud de etiquetas (tags en inglés) que dependen del objeto documentado, por ejemplo si es un fichero una clase o una función. La declaración de una función podría parecerse a algo como esto:

/**
 * La primera frase es un título/resumen de la función. Después del
 * punto que delimita la primera frase comienza la documentación
 * detallada. Características especiales están marcadas con una
 * etiqueta.
 * @param parametro El parámetro de la función.
 * @return La función devuelve un resultado.
 */
int mi_funcion(int parametro);

Guarda tus ficheros fuentes en Unicode si quieres tener acentos correctos en la documentación. Esto vale al menos para phpDocumentor.

Los sistemas de documentación sólo documentan declaraciones, objetos y tipos globales, ficheros y inclusiones. No documentan el cuerpo de una función ya que se supone que no es algo importante en un manual de referencia. Sin embargo ofrecen una etiqueta @internal con información interna, que sólo se compila con un cierto flag activado. De la misma forma se puede documentar o no variables y métodos privados.

Es cierto que los sistemas de documentación requieren algún esfuerzo al principio para instalar y entenderlos. Sin embargo, una vez superado esta fase ofrecen tener una documentación actualizada prácticamente en tiempo real que con sus enlaces y agrupaciones son una ayuda incluso para el autor durante el desarrollo. El entorno Eclipse ya incluye un enlace para mostrar la documentación de doxygen para código de C++.

Anuncios

Escribe tu dirección de correo electrónico para suscribirte a este blog, y recibir notificaciones de nuevos mensajes por correo.

Únete a otros 52 seguidores

Archivos

febrero 2018
L M X J V S D
« Ene    
 1234
567891011
12131415161718
19202122232425
262728