4.3 Generación Automática de Documentación (Recuperado)
4.3 Generación Automática de Documentación (Recuperado)
4.3 Generación Automática de Documentación (Recuperado)
Objetivos:
1
Lenguaje de Programación C++
Unidad IV. Recomendaciones integración de código
En esta sección se describe cómo poner los comentarios en el código de tal manera que
Doxygen los incorpore en la documentación que genera.
Doxygen documenta archivos, funciones, clases, miembros y atributos, siendo estos últimos
temas por ver en unidades posteriores.
/**
<...texto...>
*/
2
Lenguaje de Programación C++
Unidad IV. Recomendaciones integración de código
/*!
<...texto...>
*/
También existe la alternativa de colocar asteriscos al comienzo de cada línea dentro del bloque
de comentarios, como se muestra en los siguientes ejemplos.
/**
* <...texto...>
*/
/*!
* <...texto...>
*/
El bloque de comentarios especial puede contener una descripción breve y una descripción
detallada, esta última siendo opcional. Si ambas se redactan, primeramente se coloca la
descripción breve y se separa con una línea en blanco de la descripción detallada, por ejemplo
/**
* <Una línea corta de descripción breve>
*
* <Descripción detallada en todas las líneas que sean necesarias>
*/
Para el encabezado de un archivo, los campos comúnmente utilizados son @file, @author,
@date, @version y @section. Enseguida se muestra un ejemplo:
3
Lenguaje de Programación C++
Unidad IV. Recomendaciones integración de código
/**
* @file <nombre del archivo>
* @author <nombre del autor y se puede agregar su correo electrónico>
* @version <número de versión>
* @date <fecha de creación o última revisión>
*
* @section LICENCIA
*
* <descripción de la licencia que posee, pueden utilizarse múltiples
* líneas escritas y líneas en blanco>
*
* @section DESCRIPCIÓN
*
* <descripción breve y/o detallada, pueden utilizarse múltiples
* líneas escritas y líneas en blanco >
*/
Con el campo de @section, se pueden redactar los apartados que se deseen. En el encabezado se
debe especificar que la descripción es una sección. Para fines del curso, los campos que se pide
conservar para los ejercicios de esta Unidad, y las siguientes, son como mínimo @file, @author,
@date y @section DESCRIPCIÓN.
Luego, para funciones se utilizan los campos @param y @return en su bloque de comentarios.
El siguiente código presenta un ejemplo:
/**
* <Una línea corta de descripción breve>
*
* <Descripción detallada en todas las líneas que sean necesarias>
*
* @param parametro1 Descripción del parametro1 de entrada de la función
* @param parámetro2 Descripción del parametro2 de entrada de la función
* ...
* @return Descripción del valor de salida de la función
*/
Es posible especificar que el bloque de comentarios especial se encuentra después del código a
comentar, agregando el signo < en el primer delimitador del bloque. Por ejemplo:
Este tipo de bloque se comentarios se utiliza generalmente para descripciones breves en las
declaraciones de funciones y miembros de una clase (tema por ver en la Unidad 6).
4
Lenguaje de Programación C++
Unidad IV. Recomendaciones integración de código
Existen otros estilos para estos bloques de comentarios especiales, pero no entraremos
en detalle en este curso. Si se desea conocer estos estilos, la página oficial de Doxygen
presenta descripciones y ejemplos, véase
http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html
Ejecutando Doxygen
Existen varias formas de ejecutar Doxygen: por línea de comandos (terminal o símbolo del
sistema) o por la interfaz gráfica Doxywizard.
Si se desea conocer con mayor detalle las formas de ejecución de Doxygen y las
diferentes opciones de configuración, véase la información de la liga:
http://www.stack.nl/~dimitri/doxygen/manual/starting.html
Code::Blocks presenta el plugin DoxyBlocks que integra a Doxygen. Este plugin se encuentra
en la barra de menús y se muestra en la siguiente figura las opciones que despliega.
La primera opción “Doxywizard…” abre la interfaz gráfica Doxywizard. Otra forma más
directa es la segunda opción “Extract documentation” la cual se enlaza con Doxywizard
automáticamente y genera la documentación con la configuración por defecto de Doxygen.
5
Lenguaje de Programación C++
Unidad IV. Recomendaciones integración de código
La opción “Block comment” inserta la plantilla del bloque de comentarios especial donde se
encuentre el cursor. La opción “Line comment” inserta, donde se encuentre el cursor, los
delimitadores del tipo de bloque de comentarios especial que se encuentra después del código a
comentar.
6
Lenguaje de Programación C++
Unidad IV. Recomendaciones integración de código
Para abrir Doxywizard tenemos dos opciones: abrir desde Code::Blocks en la pestaña de
DoxyBlocks o abrir en las aplicaciones instaladas en la computadora. Al abrir Doxywizard se
presenta el siguiente cuadro de diálogo:
7
Lenguaje de Programación C++
Unidad IV. Recomendaciones integración de código
En la sección “Step 1” debe indicarse la ruta a la carpeta existente desde la cual se ejecutará
Doxygen.
Para indicar que se active el parámetro EXTRACT_ALL (que indica se extraiga toda la
documentación del código fuente al archivo HTML), se da click en la pestaña de “Expert” de la
parte izquierda de “Step 2”. Luego, se selecciona el tópico “Build”. Se verifica que la casilla de
verificación de EXTRACT_ALL se encuentre palomeada. El cuadro de diálogo que se observa
es el siguiente:
8
Lenguaje de Programación C++
Unidad IV. Recomendaciones integración de código
9
Lenguaje de Programación C++
Unidad IV. Recomendaciones integración de código
Para que los acentos se observen en la documentación, es necesario cambiar otro parámetro.
En el tópico “Input” se encuentra el parámetro INPUT_ENCODING y debe tener el valor de
ISO-8859-1. La figura siguiente lo muestra.
Ya que están todos estos parámetros indicados, se puede ejecutar Doxygen dirigiéndose a la
pestaña “Run” y dar click en el botón “Run doxygen”, que se observa en la siguiente figura.
10
Lenguaje de Programación C++
Unidad IV. Recomendaciones integración de código
A partir de esta Unidad, se pedirá incluir también el tipo de documentación de código por
Doxygen en las actividades del curso. El código de U4_3_ejemploDoxygen muestra un ejemplo
de la documentación de código que puede servir de guía.
11