doxygen manual de referencia_v2

5/10/2018 Doxygen Manual de Referencia_v2 - slidepdf.com

http://slidepdf.com/reader/full/doxygen-manual-de-referenciav2 1/9

[DOXYGEN] El presente documento tiene la finalidad de servir como guía para la utilización delsoftware Doxygen.



INTRODUCCIÓN. El presente manual describe, en forma resumida, la utilización de Doxygen v1.7 parala generación dinámica de documentación para el presente proyecto.

A continuación, se describirá de manera breve la forma en que se deberá dedocumentar el código y la organización de los archivos, además de mostrar de maneraresumida, los comandos utilizados por Doxygen para generar la documentación.

DOXYGEN

De manera rápida, Doxygen es una aplicación que construye de forma automáticauna descripción sobre el código de un proyecto, es decir crea una “documentación”

basada en los comentarios descritos dentro del mismo código en un formato enespecífico. Por lo que, si los comentarios en el código noSiguen esta sintaxis, doxygen no los reconocerá apropiadamente.

Primeramente, el software se encuentra disponible para su descarga en:

http://www.stack.nl/~dimitri/doxygen/download.html#latestman

No es necesario tener instalado el software para realizar los comentarios, por lo quesolo se utiliza al final. El proceso de instalación no representa mayor problema, en laconfiguración inicial se deberá de definir:



Nombre del proyecto. Una descripción del proyecto. la versión del proyecto. Logotipo (Imagen)

La carpeta en donde se encuentra el código a documentar. Una carpeta destino, en donde se guardara la documentación generada.

Estos atributos aparecerán en la portada de la publicación, con excepción de las rutasde directorios, de por lo que es importante definirlos de manera breve y concisa.Además, se deberá de especificar la ruta en la que se encuentra el código adocumentar (*Importante: marcar la opción de recursividad para tomar en cuentalas subcarpetas) y la ruta en la que se guardara la publicación creada.

Antes de continuar, la forma en la que está estructurado el sistema, es decir la formaen la que se encuentran ordenados los archivos, es IMPORTANTE para construirordenadamente la publicación, se recomienda crear la documentación por módulos

para brindar mayor legibilidad, esto seria simplemente indicarle a Doxygen lascarpetas por separado, para cada una de las funcionalidades. Una vez definidos estosdatos damos “clic” en siguiente, marcando las opciones como se muestra :

Al final, presionamos “Next ” (siguiente).

Dependiendo del

lenguaje.



En la siguiente pantalla se pueden producir cinco tipos de resultados:

HTML

LaTeX Man pages

RTF XML

Dependiendo de las necesidades, siendo los más claros HTML y RTF. Es posibleademás seleccionar el lenguaje y, hasta cierto punto, el aspecto, en el caso de HTML.Para este ejemplo se utiliza:



La siguiente pantalla, quedaría:

En la siguiente pestaña, Expert:

Campo que describe las

opciones.

Lista de temas,

que se pueden

configurar



Esta pestaña contiene especificaciones técnicas que permiten “refinar” u “optimizar” ladocumentación del proyecto. Para situaciones que pudieran considerarse como“normales”, se utiliza la configuración por default, por lo que no será necesariomodificarla.

Sin embargo, si se desea profundizar en los detalles que ofrece esta sección sedescribe la interfaz en la captura de pantalla anterior.

En la pestaña, “run ”.

El botón “Show configuration ” despliega, en la parte central, la información deconfiguración del proyecto. El botón de “save log ” permite generar un archivo log delproyecto. La opción de “Run doxygen ” genera la documentación del proyecto en eldirectorio especificado en el primer paso.



El resultado se muestra como sigue:

“Show HTML output ”, mostrara el resultado.

1. Documentación del código.

De manera concisa, se utiliza:

Al encabezado del archivo:

/*! \file Nombre del archivo* \brief Descripcion.*

* detalles.** \author Created by.* \date 00/00/00.**/

En este comentario, “detalles ” debe de ser utilizado para agregar las notas que secrean pertinentes acerca del archivo. La notación de “@author ”, que se mencionabadentro del correo electrónico, es propia de JAVA aunque también funciona con C, porlo que cualquiera de las dos formas es correcto. Se sugiere que sea de esta forma,porque funciona de manera “general ”.



Para nombrar los objetos como clases o funciones se utilizara:

//! nombre del objeto y tipo. /*!Descripción del objeto.*/

Ejemplo: //! A test class. /*!A more elaborate class description.*/

class Test {}

Importante : Para estos comentarios, es importante conservar los espacios y manejarlo de la forma en la que se muestra.

Esta notación también se puede utilizar para nombrar otros objetos, como lasestructuras.

Variables:

/*! \var tipo y nombre de la variable. \brief pequeña descripción.Detalles.*/

Ejemplo:

/*! \var int control* \brief A type definition for control .**Details.*/

int control;

Esta notación sirve para cualquiera de las variables del sistema, para aquellas quesean críticas y se desea agregar información extra se puede utilizar la siguientenotación:

int var; /**< Detailed description after the member */

Advertencias (Warning)

Si es necesario agregar alguna advertencia de modificación o uso incorrecto,simplemente se agrega a la parte final del comentario, dejando un espacio en blanco,el comando \warning seguido de la descripción. Ejemplo:

/*! \var enum* \brief una variable enum.*

* \warning EJEMPLO! La variable enum puede estallar*/

enumVar;



Este sirve no solo para las variables, si no para cualquier objeto que se puedacomentar, incluyendo el encabezado del archivo.

Otros comandos:

\struct to document a C-struct. \union to document a union. \enum to document an enumeration type. \fn to document a function.

\def to document a #define. \typedef to document a type definition. \namespace to document a namespace. \package to document a Java package. \interface to document an IDL interface. @param xxx yyy Esto documenta un parámetro (xxx) con una descripción

(yyy). @return yyy Documenta el valor retornado (yyy) por el método (o función). @note agregar una nota.

Los 3 utltimos, también pueden ser utilizados, ya sea con esa notación o sustituyendo“@” por “ \ ”. Estos utilizan el mismo formato que el utilizado para variables, ejemplo:

/*! \enum An enum.* \brief More detailed enum description.** Details.*/

Estos brindan un mejor detalle a la documentación y pudiera decirse que soncomplementarios, ya que con los primeros que fueron descritos se logra un buen nivelde precisión.

doxygen manual de referencia_v2

Documents