Upload
osanna
View
37
Download
2
Embed Size (px)
DESCRIPTION
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. Contexto Docente: - PowerPoint PPT Presentation
Citation preview
Using Doxygen to generate Spanish and English documentationUsing Doxygen to generate Spanish and English [email protected]@ecci.ucr.ac.cr
Universidad de Costa RicaUniversidad de Costa RicaEscuela de Ciencias de laEscuela de Ciencias de la
Computación e InformáticaComputació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 documentationUsing Doxygen to generate Spanish and English [email protected]@ecci.ucr.ac.cr
Universidad de Costa RicaUniversidad de Costa RicaEscuela de Ciencias de laEscuela de Ciencias de la
Computación e InformáticaComputació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 documentationUsing Doxygen to generate Spanish and English [email protected]@ecci.ucr.ac.cr
Universidad de Costa RicaUniversidad de Costa RicaEscuela de Ciencias de laEscuela de Ciencias de la
Computación e InformáticaComputació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 documentationUsing Doxygen to generate Spanish and English [email protected]@ecci.ucr.ac.cr
Universidad de Costa RicaUniversidad de Costa RicaEscuela de Ciencias de laEscuela de Ciencias de la
Computación e InformáticaComputación e Informática
EspecificaciónLa 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 documentationUsing Doxygen to generate Spanish and English [email protected]@ecci.ucr.ac.cr
Universidad de Costa RicaUniversidad de Costa RicaEscuela de Ciencias de laEscuela de Ciencias de la
Computación e InformáticaComputació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 decir3) No ambigua
Using Doxygen to generate Spanish and English documentationUsing Doxygen to generate Spanish and English [email protected]@ecci.ucr.ac.cr
Universidad de Costa RicaUniversidad de Costa RicaEscuela de Ciencias de laEscuela de Ciencias de la
Computación e InformáticaComputació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 documentationUsing Doxygen to generate Spanish and English [email protected]@ecci.ucr.ac.cr
Universidad de Costa RicaUniversidad de Costa RicaEscuela de Ciencias de laEscuela de Ciencias de la
Computación e InformáticaComputación e Informática
Bloque de documentación para el inglés // CSV.h (C) 2008 [email protected] // ...
#ifdef English_dox /** Deletes \c ch when it's the trailing character in \c str. - The deleted character always is \c ch.
\dontinclude test_CSV.cpp \skipline test::chop() \until }} \see test_CSV::test_chop() */ #endif void chop( std::string & str , char ch=0 );
// ... // EOF: CSV.h
Using Doxygen to generate Spanish and English documentationUsing Doxygen to generate Spanish and English [email protected]@ecci.ucr.ac.cr
Universidad de Costa RicaUniversidad de Costa RicaEscuela de Ciencias de laEscuela de Ciencias de la
Computación e InformáticaComputación e Informática
Bloque de documentación en otro archivo // CSV.es.h (C) 2008 [email protected]
#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 test_CSV.cpp \skipline test::chop() \until }} \see test_CSV::test_chop() */ // ... // EOF: CSV.es.h
Using Doxygen to generate Spanish and English documentationUsing Doxygen to generate Spanish and English [email protected]@ecci.ucr.ac.cr
Universidad de Costa RicaUniversidad de Costa RicaEscuela de Ciencias de laEscuela de Ciencias de la
Computación e InformáticaComputació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 = "CSV:"OUTPUT_LANGUAGE = SpanishOUTPUT_DIRECTORY = .GENERATE_LATEX = NOGENERATE_MAN = NOGENERATE_RTF = NOCASE_SENSE_NAMES = YESINPUT_ENCODING = ISO-8859-1INPUT = CSV.cpp CSV_line.cpp test_CSV.cpp \ CSV.h CSV_line.h \ Spanish.txt# copy CSV_line.es.h+CSV.es.h Spanish.txtRECURSIVE = NOQUIET = YESJAVADOC_AUTOBRIEF = YESEXTRACT_ALL = YESEXTRACT_PRIVATE = YESEXTRACT_STATIC = YESEXTRACT_LOCAL_CLASSES = YESINLINE_INHERITED_MEMB = YESSOURCE_BROWSER = YESINLINE_SOURCES = NOSTRIP_CODE_COMMENTS = NOREFERENCED_BY_RELATION= NOREFERENCES_RELATION = NOFULL_PATH_NAMES = NO
SORT_MEMBER_DOCS = NOSORT_BRIEF_DOCS = NOCLASS_DIAGRAMS = YES
ENABLE_PREPROCESSING = YESMACRO_EXPANSION = YESEXPAND_ONLY_PREDEF = YESPREDEFINED = "DOXYGEN_COMMENT" \ "Spanish_dox" \ "__cplusplus" \ "_MSC_VER=1300"EXAMPLE_PATH = .
# Manual ==> http://www.doxygen.org/manual.html
Using Doxygen to generate Spanish and English documentationUsing Doxygen to generate Spanish and English [email protected]@ecci.ucr.ac.cr
Universidad de Costa RicaUniversidad de Costa RicaEscuela de Ciencias de laEscuela de Ciencias de la
Computación e InformáticaComputació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 = CSV.cpp CSV_line.cpp test_CSV.cpp \ CSV.h CSV_line.h ***** Spanish.dxg INPUT = 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 *****
***** test_CSV.dxg PREDEFINED = "DOXYGEN_COMMENT" \ "English_dox" \ "__cplusplus" \ ***** Spanish.dxg PREDEFINED = "DOXYGEN_COMMENT" \ "Spanish_dox" \ "__cplusplus" \ *****
Using Doxygen to generate Spanish and English documentationUsing Doxygen to generate Spanish and English [email protected]@ecci.ucr.ac.cr
Universidad de Costa RicaUniversidad de Costa RicaEscuela de Ciencias de laEscuela de Ciencias de la
Computación e InformáticaComputación e Informática
Receta:1) 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.
2) En los archivo principales va la documentación en la lengua materna, que generalemente es el inglés.
3) En otros archivos se pone la documentación para los otros lenguajes (si son pocos lenguajes, se puede usar el mismo archivo).
4) En muchos casos conviene documentar todos los campos, métodos y funciones fuera de la clase, para evitar cargar demasiado el código fuente.
5) 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 documentationUsing Doxygen to generate Spanish and English [email protected]@ecci.ucr.ac.cr
Universidad de Costa RicaUniversidad de Costa RicaEscuela de Ciencias de laEscuela de Ciencias de la
Computación e InformáticaComputació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 documentationUsing Doxygen to generate Spanish and English [email protected]@ecci.ucr.ac.cr
Universidad de Costa RicaUniversidad de Costa RicaEscuela de Ciencias de laEscuela de Ciencias de la
Computación e InformáticaComputación e Informática
Código Fuente
http://www.di-mare.com/adolfo/p/CSV/CSV.ziphttp://www.di-mare.com/adolfo/p/CSV/es/index.htmlhttp://www.di-mare.com/adolfo/p/CSV/en/index.htmlhttp://www.di-mare.com/adolfo/p/DoxEsEn.htm
¡¡¡ Muchas Gracias !!!