¿No sabes por dónde empezar? Ayúdanos normalizando artículos.
¿Tienes experiencia? Crea alguno de estos artículos de actualidad.
Diferencia entre revisiones de «Doxygen»
(Etiqueta: nuestro-nuestra) |
(Etiqueta: nuestro-nuestra) |
||
| Línea 108: | Línea 108: | ||
"Spanish_dox" \<br> "__cplusplus" \<br> "_MSC_VER=1300" \<br> "OPEN_namespace(N)=namespace N {" \<br> "CLOSE_namespace(N)=}" \<br> "USIGN_namespace(N)=using namespace N"<br> | "Spanish_dox" \<br> "__cplusplus" \<br> "_MSC_VER=1300" \<br> "OPEN_namespace(N)=namespace N {" \<br> "CLOSE_namespace(N)=}" \<br> "USIGN_namespace(N)=using namespace N"<br> | ||
| − | + | <div align="justify">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.</div><div align="justify"></div> | |
| − | |||
| − | |||
| − | |||
== Ejemplo 2 == | == Ejemplo 2 == | ||
| − | |||
/** Calcula el Máximo Común Divisor de los números \c "x" y \c "y". | /** Calcula el Máximo Común Divisor de los números \c "x" y \c "y". | ||
Revisión del 16:44 28 feb 2011
| ||||||||
Sumario
[ocultar]El generador de documentación de código fuente Doxygen
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
Soporte comercial
- Implementación de las funciones
- Corregir errores.
Resumen
El camino más sencillo es que al escribir su implementación, deben asegurarse de cumplirsiempre con estas 3 políticas de programación, que se considera las más importantes:
1. Es muy importante que el programa esté correctamente identificado y que las instrucciones estén debidamente espaciadas.
2. Es muy importante que en todo el programa haya buena documentación interna.
3. 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:
1. La falta de cualquier especificación debe ser castigada fuertemente.
2. Correcta Identificación del código fuente.
3. Correcto espaciado del código fuente.
4. Código fuente escrito de manera que sea legible y claro.
5. Uso de identificadores significativos.
Configuración 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"
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. En resumen, lo más relevante que hay que saber para usar esta herramienta es 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] 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.
