C ++: documentación creando con Doxygen

La mayoría de los programadores odian para crear la documentación aún más de lo que odian a comentar su propio código. Introduzca Doxygen, que permite a los programadores incrustar etiquetas en los comentarios que luego se pueden extraer para crear la documentación.

Instalación de Doxygen

Doxygen no viene con Code :: Blocks (al menos no de este escrito). Tendrá que descargar la versión correcta de Doxygen para su aplicación. (También hay un enlace a la página web desde el sitio Doxygen Code :: Blocks.) Después de vincular a la página web Doxygenorg, puede navegar a la página de descarga y encontrar la versión de Doxygen para su sistema operativo, como se muestra aquí:

Descargar e instalar la versión más adecuada para su sistema operativo. Puede aceptar los valores predeterminados, pero recuerda que el asistente de instalación coloca el archivo ejecutable Doxygen.

Ahora empieza Code :: Blocks. Seleccione Preferencias → DoxyBlocks abiertas. Desde allí, seleccione la ficha General y establecer la ruta a Doxygen. (Este es el camino que anotó en el párrafo anterior.) La ruta predeterminada para Windows es C: Program Filesdoxygenbindoxygen.exe. Haga lo mismo para el Camino a doxywizard. Aquí el valor por defecto para Windows es C: Program Filesdoxygenbindoxywizard.exe. Puede dejar las otras herramientas en blanco, ya que no son necesarios cuando se genera la documentación en formato HTML.

La adición de Documentación Comentarios

Doxygen utiliza los comentarios especiales a palabras clave bandera que ayudan a la herramienta Crear documentación. Confusamente suficiente, Doxygen acepta varias normas diferentes, pero el valor por defecto es el que más se parece a JavaDoc, la / ** comentar, lo cual está bien. (Se puede cambiar el estilo de comentarios a uno de los otros mediante la selección de DoxyBlocks → Abrir Preferencias y seleccionando la pestaña Estilo comentario.)

Para ver cómo funciona esto, coloque el cursor al comienzo de una función y seleccione DoxyBlocks → bloque de comentario (o presione Ctrl + Alt + B). Un comentario como la siguiente (los siguientes ejemplos se utiliza el programa Budget5 que aparece en el material descargable en faqsalex.info/extras/cplusplus):

/ ** ** breve lista accList parámetro&* Volverá vacía ** / getAccounts void (lista& accList) {

Code :: Blocks inserta un comentario de bloque a partir de Doxygen / **. Doxygen sabe que este comentario pertenece a la definición de la función que sigue inmediatamente. Doxygen palabras clave comienzan con una (Barra invertida). los breve banderas de palabras clave de la breve descripción de la función. La breve descripción puede extenderse sobre más de una línea. Esto debería ser una breve descripción de la función que aparece en las pantallas tabulares.

El programador puede seguir esta con una descripción más completa marcado con el detalles palabra clave. Esta descripción detallada da una descripción más completa de lo que hace la función.

Muchas de las palabras clave Doxygen son opcionales. En particular, la detalles Se supone palabra clave si se inicia un párrafo separado de la breve Descripción por nada más que una línea en blanco.

Más allá de eso es una línea separada marcado con la palabra clave PARAM para describir cada argumento de la función. Finalmente, el regreso palabra clave describe el valor devuelto por la función.

Cuando completado, el comentario de Doxygen getAccounts () podría aparecer como sigue:

/ ** breves getAccounts - Cuentas entradas desde el teclado * detalles Esta función lee la entrada desde el teclado * Por cada S o C introducido, la función crea un nuevo Ahorros * o Comprobación objeto de cuenta y lo añade a la lista de cuentas. *. Una X termina la entrada. Cualquier otra entrada * se supone que es un depósito (números mayores que * 0) o una retirada (los números de menos de 0). ** lista accList PARAM& la lista de cuenta * objetos creados por getAccounts () * volverá vacía * / void getAccounts (lista& accList) {

También puedes dejar un comentario Doxygen en la misma línea. Esto se utiliza más a menudo al comentar los miembros de datos. Coloque el cursor al final de la línea y seleccionar DoxyBlocks → Línea Comentario o presione Ctrl + Alt + L. Ahora rellenar una descripción del miembro de datos. El resultado aparece como en el siguiente ejemplo también tomada de Budget5:

Video: Documentacion de código con Doxygen

doble equilibrio - / ** lt; el saldo de la cuenta corriente * /

Generación de documentación Doxygen

Doxygen puede generar la documentación en varios formatos diferentes, aunque algunos (como HTML compilado) requieren descarga adicional. El formato HTML es particularmente conveniente ya que no requiere nada más que un navegador para ver.

Video: Doxygen

El valor por defecto es HTML, pero si desea cambiar el formato, seleccione Preferencias → DoxyBlocks abiertas, a continuación, seleccione los valores predeterminados Doxyfile 2 pestaña. En esta ventana puede seleccionar todos los diferentes formatos que desea generar.

Antes de extraer la documentación de la primera vez, es probable que desee para seleccionar algunas otras opciones. Seleccione Preferencias DoxyBlocks → Abrir y, a continuación, seleccione la ficha Valores predeterminados Doxyfile. Asegúrese de que el Extraer todo casilla está marcada. A continuación, seleccione la pestaña Doxyfile predeterminados 2 y comprobar los Class_Diagrams casilla de verificación. A continuación, seleccione la ficha General y seleccione la opción Ejecutar HTML cuadro Después de Compilación. Haga clic en OK, y ya está. (Usted no tendrá que volver a hacer esto ya que las opciones se guardan en un archivo llamado doxyfile).

Video: Using Doxygen to document computing projects

Seleccione DoxyBlocks → Extracto de Documentación para generar y ver la documentación. Después de un intervalo bastante corto, Doxygen abre su navegador favorito con la documentación como la mostrada en la siguiente figura.

Doxygen no es muy fácil de usar cuando se trata de errores de entrada. A veces Doxygen sólo se detiene la generación de la documentación en algún momento de su fuente por ninguna razón obvia. Compruebe el archivo doxygen.log contenida en el mismo directorio que el doxyfile de los errores que puedan haber ocurrido durante la extracción.

La siguiente imagen muestra el explorador de proyectos en la ventana de la izquierda, que permite al usuario navegar dentro de la documentación del proyecto. A la derecha, el getAccounts () función ha sido seleccionada con el fin de obtener una descripción más detallada. La breve descripción aparece en la primera línea, seguido por la descripción detallada, los parámetros y el valor de retorno:

La documentación de la clase es de manera similar a fondo como lo demuestra el siguiente fragmento de código.

/ ** Cuenta clase * Breve resumen de una cuenta bancaria * Detalles Esta clase abstracta incorpora * propertiescommon a ambos tipos de cuenta:. * Corrientes y de ahorro. Sin embargo, le falta el concepto de retirada * (), que es diferente * entre la cuenta de dos * / clase {

La documentación para Cuenta se muestra a continuación:

Video: Videotutorial doxygen esp

Note la descripción que aparece en la clase Cuenta. Esta es la breve descripción. Al hacer clic en Más le llevará a la descripción detallada. Observe también la representación gráfica de la relación entre la herencia Cuenta, sus clases padre, y sus clases infantiles.