Doxygen
| ||||||||
Doxygen. Es de uso fácil por lo que es la herramienta ideal para ser usada con principiantes. Es un generador de documentación para C++,C, Java, Objective-C, Python, IDL (versiones Corba y Microsoft) y en cierta medida para PHP, C# y D. Dado que es fácilmente adaptable, funciona en la mayoría de Sistemas Unix así como en Windows y Mac OS X. La mayor parte del código de Doxygen está escrita por Dimitri van Heesch.
Sumario
El generador de documentación de código fuente Doxygen
Es una buena ocasión para presentar muy brevemente un utilitario que no puede faltar en ninguna «caja de herramientas» de un buen programador. Doxygen es un programa que permite documentar fácilmente el código a través de un sistema de «comentarios-tags». Así por ejemplo, los usuarios de Javadoc, encontraran que disponen de un procedimiento de 170 tags por defecto, en un sistema que les permitirá agregar los propios a los efectos de responder a las necesidades de un proyecto. Aparte de ello, de la documentación de las fuentes (prototipo de funciones, de las clases) podemos obtener las siguientes informaciones:
- Listado de archivos incluidos
- Documentación de las estructuras de datos
- Jerarquía de las clases
- Diferentes tipos de gráficos: diagrama de clases, de colaboraciones, de llamadas, de inclusión, etc.
- Un index de todos los identificadores
- Los archivos fuente anotados
Toda la documentación producida generalmente es en formato HTML, a causa de su facilidad de utilización, sin embargo también es posible obtener archivos de formato LATEX, PostScript, PDF, XML, man e incluso Word y CHM. Una gran parte de Doxygen ha sido escrita por Dimitri van Heesch, quien en su época encontraba a la documentación generada por Qt como muy bonita y doc++ como demasiado limitada para un trabajo similar. Hoy, Doxygen soporta C/C++, Java (Corba y Microsoft) Java, Python, IDL, C#, Objetive-C y en parte D y <span style="text-decoration: underline;" />PHP. Doxygen esta distribuido bajo licencia GNU GPL, esta disponible un binario para Windows 95 / XP y para Mac OS X, pero necesita la librería libqt.
Soporte comercial
Actualmente se investiga las posibilidades de prestar apoyo comercial para doxygen. Las formas de apoyo son:
- Implementación de las funciones
- Corregir errores.
Resumen
Para la mayor parte de los programadores la codificación de algoritmos es la parte más interesante de la construcción de programas; los mismos trabajan creando mundos virtuales, en donde todas las variables coexisten bajo un perfecto control: esta es la parte más creativa del trabajo del programador. Para construir programas se desde las estructuras de datos y algoritmos avanzados, hasta la aplicación de convenciones como las descritas en DiM-1988, que facilitan la labor y mantenimiento del programa. El camino más sencillo es que al escribir su implementación, se debe cumplir siempre con estas 3 políticas de programación.
- El programa debe estar correctamente identificado y las instrucciones debidamente espaciadas.
- Todo el programa debe tener una buena documentación interna.
- Uso de Doxygen para la especificación de todos los métodos, funciones y campos de la clase.
Se debe saber cuál es la forma de calificar proyectos programados. Específicamente, se concentran en encontrar fallas que quiebren alguna de estas 5 reglas:
- La falta de cualquier especificación debe ser castigada fuertemente.
- Correcta Identificación del código fuente.
- Correcto espaciado del código fuente.
- Código fuente escrito de manera que sea legible y claro.
- Uso de identificadores significativos.
Configuración Doxygen
Doxygen es un sistema de documentación para C++, C, Java, Objective-C, Python, IDL (Corba y los sabores Microsoft) y, hasta cierto punto, para PHP, C# y D. La ventaja principal de usar Doxygen en los cursos universitarios es que le permite al estudiante obtener entrenamiento en el uso herramientas que ayudan a generar documentación con la ventaja adicional de que Doxygen es aplicable a un rango muy amplio de lenguajes, lo que no ocurre con herramientas de aplicación específica como Javadoc NDK-1997. Cuando el estudiante termina sus estudios universitarios y pase a su carrera profesional, su entrenamiento Doxygen le permitirá usar con comodidad cualquier otra herramienta de documentación, inclusive Javadoc, cuyo formato es compatible con Doxygen.
Ejemplo 1
PROJECT_NAME = "Prueba de la clase rational:"
OUTPUT_LANGUAGE = Spanish
OUTPUT_DIRECTORY = .
GENERATE_LATEX = NO
GENERATE_MAN = NO
GENERATE_RTF = NO
CASE_SENSE_NAMES = YES
INPUT_ENCODING = ISO-8859-1
INPUT = rational.h rational.cpp rat-calc.cpp \rat-tst.cpp ADH_port.h
RECURSIVE = NO
QUIET = YES
JAVADOC_AUTOBRIEF = YES
EXTRACT_ALL = YES
EXTRACT_PRIVATE = YES
EXTRACT_STATIC = YES
EXTRACT_LOCAL_CLASSES = YES
INLINE_INHERITED_MEMB = YES
SOURCE_BROWSER = YES
INLINE_SOURCES = NO
STRIP_CODE_COMMENTS = NO
REFERENCED_BY_RELATION= NO
REFERENCES_RELATION = NO
FULL_PATH_NAMES = NO
SORT_MEMBER_DOCS = NO
SORT_BRIEF_DOCS = NO
CLASS_DIAGRAMS = YES
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
PREDEFINED = "DOXYGEN_COMMENT" \
"Spanish_dox" \
"__cplusplus" \
"_MSC_VER=1300" \
"OPEN_namespace(N)=namespace N {" \
"CLOSE_namespace(N)=}" \
"USIGN_namespace(N)=using namespace N"
El ejemplo 1 muestra el archivo "rat-tst.dxg" que se puede usar de plantilla para obtener el archivo de configuración para que Doxygen genere la documentación de uno o más módulos. Para esto, basta modificar únicamente el renglón "INPUT" que contiene la lista de archivos de donde Doxygen extraerá la documentación. En este ejemplo, Doxygen generó documentación usando como entrada los siguientes archivos: "rational.h", "rational.cpp", "rat-calc.cpp", "rat-tst.cpp" y "ADH_port.
Ejemplo 2
/** Calcula el Máximo Común Divisor de los números \c "x" y \c "y".
- mcd(x,y) >= 1 siempre.
- MCD <==> GCD: Greatest Common Divisor .
\pre
(y != 0)
\remark
Se usa el algoritmo de Euclides para hacer el cálculo.
\par Ejemplo:
\code
2*3*5 == mcd( 2*2*2*2 * 3*3 * 5*5, 2*3*5 )
30 == mcd( -3600, -30 )
\endcode
/ long mcd(long x, long y) {
long g = (x < 0 ? -x : x); // trabaja con valores positivos
long r = (y < 0 ? -y : y); // "r" es el resto
long temp;
do {
temp = r;
r = g % r;
g = temp;
} while (0 != r);
return g;
} // mcd()
El estilo Doxygen de documentación es bastante simple e intuitivo, como se muestra en el ejemplo 2. Para usar la herramienta se tendra en cuenta lo siguiente:
- La documentación Doxygen comienza con el marcador de principio de comentario "/**" y termina en "*/". Esto permite mezclar la documentación con el código fuente lo que ayuda mucho a que la documentación quede actualizada cuando se le da mantenimiento a un módulo.
- El primer renglón de la documentación permite definir para qué sirve el artefacto de programación. Este renglón finaliza con un punto "." que no hay que olvidar y es el que sale el la documentación general del módulo. Por ejemplo, se puede consultar en Internet la página descriptiva para las clases "Matrix" descrita en [[[DiM-2004|DiM-2004]]] y "rational", que es la clase usada como ejemplo en este documento:
- Los comandos especiales Doxygen "\pre", "\remarks" y "\par" permiten agregar secciones de precondición, comentarios y ejemplos a la documentación.
- También es posible incluir ejemplos de uso con los marcadores HTML "
" y "" o con sus equivalentes, los comandos especiales "\code" y "\endcode", que sirven para incluir texto usando una fuente no proporcional, similar a la fuente "Courier" generalmente usada para el código de programas.
- Doxygen también permite usar listas, las que se obtienen anteponiendo un guión al principio de cada ítem de la lista.
