Download Using Doxygen to generate Spanish and English - Di

Using Doxygen to generate Spanish and English documentation
adolfo.dimare@ecci.ucr.ac.cr
Universidad de Costa Rica
Escuela de Ciencias de la
Computación e Informática
Agenda de Trabajo
•
•
•
•
•
•
•
•
•
Contexto Docente
Doxygen
Especificación + Módulos + Reutilización
Bloques de documentación para cada idioma
Configuración Doxygen para cada lenguaje
Ejemplos de documentación Doxygen
Comparación de configuraciones
Receta
Conclusiones
Using Doxygen to generate Spanish and English documentation
adolfo.dimare@ecci.ucr.ac.cr
Universidad de Costa Rica
Escuela de Ciencias de la
Computación e Informática
Contexto Docente:
- Curso de Programación II
- Especificación + Módulos + Reutilización
- Objetivo: [ C++ ]
Introducir los fundamentos teóricos de programación para
entrenar a cada estudiante en las técnicas básicas de
construcción de programas, en especial en la especificación e
implementación de módulos y artefactos de programación
reutilizables, con el fin que pueda usar herramientas de
programación y participar en cualquier equipo dedicado a construir
programas de mediana complejidad.
Using Doxygen to generate Spanish and English documentation
adolfo.dimare@ecci.ucr.ac.cr
Universidad de Costa Rica
Escuela de Ciencias de la
Computación e Informática
Doxygen:
•
•
Dimitri van Heesch
http://www.doxygen.org
Es necesario inculcar en los programadores la
disciplina de especificar antes de programar, o
sea, de diseñar antes de construir, para
mejorar la calidad del producto final.
Using Doxygen to generate Spanish and English documentation
adolfo.dimare@ecci.ucr.ac.cr
Universidad de Costa Rica
Escuela de Ciencias de la
Computación e Informática
Especificación
La Especificación puede verse como un contrato en el que
están definidos todos los servicios que la implementación del
módulo es capaz de dar.
Reutilización
Una pieza de programación es reutilizable si puede ser usada en
la construcción de un nuevo programa o programa producto.
Módulo
Sección de un programa bien construida, con un fin específico,
y que puede ser reutilizado.
Using Doxygen to generate Spanish and English documentation
adolfo.dimare@ecci.ucr.ac.cr
Universidad de Costa Rica
Escuela de Ciencias de la
Computación e Informática
Especificación
La Especificación puede verse como un contrato en
el que están definidos todos los servicios que la
implementación del módulo es capaz de dar.
Cualidades de cada especificación
1) Completa: debe decirse todo lo que hay que decir
2) Correcta: debe omitirse lo que no hay que decir
3) No ambigua
Using Doxygen to generate Spanish and English documentation
adolfo.dimare@ecci.ucr.ac.cr
Universidad de Costa Rica
Escuela de Ciencias de la
Computación e Informática
Bloque de documentación para 2 lenguajes
#ifdef English_dox
/// Defined by the C++ standard library.
#endif
#ifdef Spanish_dox
/// Definido por la biblioteca estándar C++.
#endif
namespace std { } // trick to include it into
// the Doxygen documentation
Using Doxygen to generate Spanish and English documentation
adolfo.dimare@ecci.ucr.ac.cr
Universidad de Costa Rica
Escuela de Ciencias de la
Computación e Informática
Bloque de documentación para el inglés
// CSV.h
// ...
(C) 2008 adolfo@di-mare.com
#ifdef English_dox
/** Deletes \c ch when it's the trailing character in \c str.
- The deleted character always is \c ch.
\dontinclude
\skipline
\until
\see
test_CSV.cpp
test::chop()
}}
test_CSV::test_chop()
*/
#endif
void chop( std::string & str , char ch=0 );
// ...
// EOF: CSV.h
Using Doxygen to generate Spanish and English documentation
adolfo.dimare@ecci.ucr.ac.cr
Universidad de Costa Rica
Escuela de Ciencias de la
Computación e Informática
Bloque de documentación en otro archivo
// CSV.es.h
(C) 2008 adolfo@di-mare.com
#ifdef Spanish_dox
/// Documentación en español.
#define Spanish_dox "Documentación en español"
/// \def Spanish_dox ///< Marca bloques de documentación en español.
#endif
// …
/** \fn
void chop( std::string & str , char ch=0 );
\brief Elimina \c ch si es el último caracter de \c str.
- El caracter eliminado siempre es \c ch.
\dontinclude
\skipline
\until
\see
*/
// ...
// EOF: CSV.es.h
test_CSV.cpp
test::chop()
}}
test_CSV::test_chop()
Using Doxygen to generate Spanish and English documentation
adolfo.dimare@ecci.ucr.ac.cr
Universidad de Costa Rica
Escuela de Ciencias de la
Computación e Informática
Ejemplos de documentación Doxygen
1) Español
http://www.di-mare.com/adolfo/p/CSV/es/index.html
2) Inglés
http://www.di-mare.com/adolfo/p/CSV/en/index.html
PROJECT_NAME
OUTPUT_LANGUAGE
OUTPUT_DIRECTORY
GENERATE_LATEX
GENERATE_MAN
GENERATE_RTF
CASE_SENSE_NAMES
INPUT_ENCODING
INPUT
=
=
=
=
=
=
=
=
=
#
RECURSIVE
=
QUIET
=
JAVADOC_AUTOBRIEF
=
EXTRACT_ALL
=
EXTRACT_PRIVATE
=
EXTRACT_STATIC
=
EXTRACT_LOCAL_CLASSES =
INLINE_INHERITED_MEMB =
SOURCE_BROWSER
=
INLINE_SOURCES
=
STRIP_CODE_COMMENTS
=
REFERENCED_BY_RELATION=
REFERENCES_RELATION
=
FULL_PATH_NAMES
=
"CSV:"
Spanish
.
NO
NO
NO
YES
ISO-8859-1
CSV.cpp
CSV_line.cpp test_CSV.cpp \
CSV.h
CSV_line.h
\
Spanish.txt
copy CSV_line.es.h+CSV.es.h Spanish.txt
NO
YES
YES
YES
YES
YES
YES
YES
YES
NO
NO
NO
NO
NO
SORT_MEMBER_DOCS
SORT_BRIEF_DOCS
CLASS_DIAGRAMS
= NO
= NO
= YES
ENABLE_PREPROCESSING
MACRO_EXPANSION
EXPAND_ONLY_PREDEF
PREDEFINED
=
=
=
=
EXAMPLE_PATH
YES
YES
YES
"DOXYGEN_COMMENT"
"Spanish_dox"
"__cplusplus"
"_MSC_VER=1300"
= .
\
\
\
# Manual ==> http://www.doxygen.org/manual.html
Using Doxygen to generate Spanish and English documentation
adolfo.dimare@ecci.ucr.ac.cr
Universidad de Costa Rica
Escuela de Ciencias de la
Computación e Informática
Comparación de configuraciones
Comparing files test_CSV.dxg and Spanish.dxg
***** test_CSV.dxg
PROJECT_NAME
= "CSV:"
OUTPUT_LANGUAGE
= English
OUTPUT_DIRECTORY
= .
***** Spanish.dxg
PROJECT_NAME
= "CSV:"
OUTPUT_LANGUAGE
= Spanish
OUTPUT_DIRECTORY
= .
*****
***** test_CSV.dxg
INPUT
***** Spanish.dxg
INPUT
#
*****
***** test_CSV.dxg
PREDEFINED
***** Spanish.dxg
PREDEFINED
*****
= CSV.cpp
CSV.h
CSV_line.cpp test_CSV.cpp \
CSV_line.h
= CSV.cpp
CSV_line.cpp test_CSV.cpp \
CSV.h
CSV_line.h
\
Spanish.txt
copy CSV_line.es.h+CSV.es.h Spanish.txt
= "DOXYGEN_COMMENT"
"English_dox"
"__cplusplus"
\
\
\
= "DOXYGEN_COMMENT"
"Spanish_dox"
"__cplusplus"
\
\
\
Using Doxygen to generate Spanish and English documentation
adolfo.dimare@ecci.ucr.ac.cr
Universidad de Costa Rica
Escuela de Ciencias de la
Computación e Informática
Receta:
1)
2)
3)
4)
5)
Marque el bloque de código con una macro para cada lenguaje,
como por ejemplo "English_dox" para el inglés y "Spanish_dox"
para el español.
En los archivo principales va la documentación en la lengua
materna, que generalemente es el inglés.
En otros archivos se pone la documentación para los otros
lenguajes (si son pocos lenguajes, se puede usar el mismo
archivo).
En muchos casos conviene documentar todos los campos,
métodos y funciones fuera de la clase, para evitar cargar
demasiado el código fuente.
Pese a que cada bloque de documentación debe estar rodeado
por la pareja #ifdef - #endif que corresponde al lenguaje, el código
resultante es legible.
Using Doxygen to generate Spanish and English documentation
adolfo.dimare@ecci.ucr.ac.cr
Universidad de Costa Rica
Escuela de Ciencias de la
Computación e Informática
Conclusión
Doxygen es una herramienta ideal para documentar
pues se usa en proyectos diversos y valiosos.
Con un pequeño esfuerzo es posible mantener la
documentación para varios lenguajes sin ensuciar
demasiado el código fuente.
Especifique + Pruebe + Construya.
Using Doxygen to generate Spanish and English documentation
adolfo.dimare@ecci.ucr.ac.cr
Universidad de Costa Rica
Escuela de Ciencias de la
Computación e Informática
Código Fuente
http://www.di-mare.com/adolfo/p/CSV/CSV.zip
http://www.di-mare.com/adolfo/p/CSV/es/index.html
http://www.di-mare.com/adolfo/p/CSV/en/index.html
http://www.di-mare.com/adolfo/p/DoxEsEn.htm
¡¡¡ Muchas Gracias !!!