Doxygen
| ||||||||
El generador de documentación de código fuente Doxygen
- 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
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
- 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
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"
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()
- 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.