Doxygen
Contents
1. file brief 2 1 Mux using with select Use standard library library ieee Use logic elements use ieee std_logic_1164 all Mux entity brief description Detailed description of this mux design element entity mux_using_with is port din_0 in std_logic Mux first input din_1 in std_logic Mux Second input sel in std_logic Select input mux_out out std_logic Mux output end entity QObrief Architure definition of the MUX Odetails More details about this mux element architecture behavior of mux_using_with is begin with sel select mux out lt din O when 0 din 1 when others 29 end architecture Para obtener una salida apropiada debe setear la opci n OPTIMI ZE_OUTPUT_VHDL en YES en el archivo de configuraci n de Doxy gen 15 6 Otros e 1 Este comando escribe el simbolo a la salida e gt Este comando escribe el simbolo gt a la salida e 1 lt Este comando escrible el s mbolo lt a la salida e Este comando escribe el s mbolo a la salida e 1 Este comando escrible el s mbolo a la salida e amp Este comando escribe el simbolo a la salida 16 Referencias La informaci n anterior se extrajo y tradujo del manual de Doxygen http www doxygen org Cecilia Chialchia ceciliachQiar unlp edu ar 302. 13 3 Anidando comandos a 14 Links a documentaci n externa 15 Comandos Especiales 15 1 Formato de texto o 15 2 Indicadores Estructurales 15 3 Indicadores de secci n e 15 4 Indicadores de links a a 15 5 Bloques 15 6 Otros 16 Referencias especiales de documentaci n en VHDL 20 20 20 21 22 24 24 25 27 28 29 30 30 1 Instalaci n Primero necesita obtener la ltima versi n de Doxygen de la p gina web http www doxygen org Adem s usted necesitar Las herramientas GNU flex bison GNU make y strip Para generar un Makefile necesitar perl El script de configuraci n asumir que usted posee las herramientas de Unix como sed date find uname mv cp cat echo tr cd y rm Para hacer uso de todas las caracter sticas de Doxygen deber instalar tam bien las siguientes herramientas a Una distribuci n de IXTEX por ejemplo teTeX 1 0 esto es necesario para generar las salidas Latex PostScript y PDF a Graphviz Graph visualization toolkit versi n 1 8 10 o mayor Nece saria para inclu r los gr ficos a Un intrprete de ghostscript a Python para genera la documentaci n propia de doxygen 2 Compilaci n Compilaci n 1 gunzip doxygen VERSION src tar gz descomprime el archivo 2 tar xf dorygen VERSION src tar desempaqueta el archivo 3 ejecute el script configure s
3. K E kkk kk kkk kk kkk o bien AAA comentarios 111111111111111 10 Para las descripciones breves brief tambin existen varias posibilidades Puede usar el comando brief con alguno de los bloques de comentarios anteriores Este comando termina al final del p rrafo as la descripci n detallada contin a luego de una l nea en blanco N brief descripci n breve continua la descripci n brermina en el primer punto seguida de un espacio o una nueva l nea Descripci n breve que termina aqu Descripci n detallada continua aqu o bien Descripci n breve que termina aqu Descripci n detallada continua aqu Doxygen s lo permite una descripci n breve y una detallada 7 1 Documentando miembros Si desea documentar los miembros de un archivo estructura union class o enum debe colocar un marcador lt en el bloque int var lt descripci n despu s del miembro int var lt descripci n detallada despu s del miembro int var lt descripci n detallada despu s del miembro lt int var lt descripci n detallada despu s del miembro lt Generalmente se desear colocar una describpci n breve luego de un miembro esto se realiza de la siguiente manera int var lt descripci n breve despu s del miembro 11 O bien int var lt Descripci n breve despu s del miembro N tese que estos bloques tienen la documentaci
4. documentaci n en TEX en lugar de un link se escribe el n mero de p gina Ade m s el ndice al final del documento puede utilizarce para encontrar rapidamente la documentaci n de una clase miembro namespace o 18 archivo Para las p ginas man no se generan referencias Las pr ximas secciones muestran como generar links a las entidades documentadas en un archivo fuente 12 1 Links a p ginas web y direcciones de mail Doxygen reemplazar autom ticamente las URLs y direcciones de mail que encuentre en la documentaci n por links en HTML 12 2 Links a archivos Todas las palabras que contengan un punto que no sea el ltimo caracter de la palabra son considerados nombres de archivos Si la pa labra es el nombre de un archivo documentado de entrada se generar autom ticamente un link a la documentaci n de ese archivo 12 3 Links a funciones Se crear n links a funciones si es encontrado uno de los siguientes patrones 1 lt functionName gt lt argument list gt 2 lt functionName gt 3 lt functionName gt 4 lt className gt n lt functionName gt lt argument list gt 5 lt className gt n lt functionName gt lt argument list gt 6 lt className gt n lt functionName gt 7 lt className gt n lt functionName gt con n gt 0 12 4 Links a variables typedefs enum types enum va lues y defines Todas stas entidades pueden ser referidas de la mi
5. en el mismo parrafo Mas texto en un nuevo parrafo 9 2 Usando comandos HTML Si lo desea puede usar comandos HTML dentro de los bloques de docu mentaci n Utilizar estos comandos tiene la ventaja de ser un mtodo m s natural para los tems de listas que consisten de m ltiples p rrafos 14 10 Agrupar Doxygen posee tres mecanismos para agrupar Un mecanismo trabaja a nivel global creando una nueva p gina para cada grupo Estos grupos son llamados modulos en la documentaci n El segundo mecanismo trabaja dentro de una lista de miembros de alguna entidad compuesta y es llamado grupos de miembros member groups Para las p ginas existe un tercer mecanismo llamado sub paginar subpaging 10 1 M dulos M dulos es una manera de agrupar cosas en p ginas separadas Se puede documentar un grupo como un todo as tambin como todos los miembros individuales Los miembros de un grupo pueden ser archivos namespaces clases funciones variables enums typedefs y defines pero tambin otros grupos Para definir un grupo debe colocarse el comando Adefgroup en un blo quero de un grupo espec fico colocando un comando lingroup dentro de su bloque de documentaci n Para evitar colocar comandos lingroup en la documentaci n por cada miembro se puede agrupar miembros abriendo un marcador antes del grupo y el marcador de cierre despus del grupo Los grupos tambin pueden ser anidados usando stos marcadores de gru pos 10 2 G
6. es lt nombre archivo gt EL texto de este archivo sera incluido en la documentacion inmediatamente des pues de la documentacion contenida en el bloque de comentarios Todos los ejemplos son colocados en una lista Puede incluirse parte del path en lt nombre archivo gt en el caso de que el nombre no sea unico Si es necesario mas de un archivo fuente para el ejemplo puede utilizarse el comando linclude file lt nombre gt Indica que un bloque de comentarios contiene documentacion para un fuente o archivo header con el nombre lt nombre gt El archivo puede incluir parte de el path si no es unico Si el nombre del archivo es omitido entonces el bloque de documentacion que contiene el comando file pertenecera al archivo en el que se encuentra Importante La doucmentacion de 25 funciones globales variables typedefs y enum solo seran incluidas en la salida si el archivo en el que se encuentran tambien esta documentado Xfn declaracion de funcion Indica que un bloque de comen tarios contiene documentacion de una funcion Este comando solo es necesario si un bloque de comentarios no se encuentra delante o detras de la declaracion o definicion de la funcion Si el bloque de comentarios esta delante de la declaracion este comando puede y para evitar redundancia deberia ser omitido Una declaracion de funcion completa incluyendo argumentos debe ser especifica da a continuacion del comando en una sola linea Importante No
7. se extiende hasta el pr ximo p rrafo Los p rrafos est n delimitados por una l nea en blanco o por un indicador de secci n e si entonces significa que el argumento es opcional Acontinuaci n se detalla una lista de los comandos m s usados 15 1 Formato de texto e la lt palabra gt escribe palabra en una fuente especial Equivalente ale e larg lt palabra gt item de una lista equivalente a e lb lt palabra gt escribe palabra en negrita e lc lt palabra gt escribe palabra en la fuente typewriter e code Comienza una secci n de bloque de c digo e lendcode Finaliza una secci n de bloque de c digo Acode e lcopydoc ref Copia documentaci n de ref e dot Comienza un bloque de gr fico dot e lenddot Finaliza un bloque de gr fico dot e 1f Comienza y finaliza una f rmula de una l nea e f Comienza un bloque de f rmula centrada e f Finaliza un bloque de f rmula centrada e limage lt formato gt lt archivo gt caption Coloca una imagen dentro de la documentacion con la caption caption e htmlonly Comienza un bloque para salida HTML nicamente e lendhtmlonly Finaliza un bloque para salda HTML nicamen te e n Fuerza una nueva l nea e verbatim Comienza un bloque inclu do como textual e lendverbatim Finaliza un bloque textual verbatim 24 15 2 Indicadores Estructurales addtogroup lt nombre gt titulo Define un grupo igual que Adefgroup pero en contraste
8. Doxygen Tutorial Resumen Doxygen es una herramienta para generar documentaci n a partir del c digo fuente Es un sistema de documentaci n para C C Ja va ObjectiveC Python IDL Corba and Microsoft flavors Fortran VHDL PHP C ndice 1 Instalaci n 4 2 Compilaci n 4 3 Comenzar 5 4 Crear un archivo de configuraci n 6 5 Generando la documentaci n 7 51 Salida HEM o a a ESO 7 o2 Dalda ATEX enaa EEES 7 gas Sala RE are a Aa de a a e ian a AS aa 7 674 Salida M do ade A taa da a a de 8 55s Salida Man adn e da te 8 6 Documentando el c digo 8 7 Bloques especiales de documentaci n 10 7 1 Documentando miembros o 11 8 Documentaci n en otros sitios 13 9 Listas 13 9 1 Usando signos MENOS e 13 9 2 Usando comandos HTML 14 10 Agrupar 15 10L M dulos dilata da als aa aaa as 15 10 2 Grupos de miembros e 15 10 3 Subpagidar e e 16 10 4 Inclu r f rmulas e o 16 11 Gr ficos y diagramas 18 12 Generaci n autom tica de links 18 12 1 Links a p ginas web y direcciones de mail 19 12 2 Links archivos dos aa AP do A a 19 12 3 Links a funciones e 19 12 4 Links a variables typedefs enum types enum values y defines 19 12 Dt pedels 3 E adranau e rs E rd ii 19 13 Comandos 13 L Altas simples a de dor ad de To Das a dd 13 2 Alias con arguMemtos e
9. E_DOT est en YES en el archivo de configuraci n HAVE_DOT indica que la herramienta dot est disponible DOT PATH es el path la herramienta dot si no est en PATH GRAPHICAL_HIERARCHY generar una representaci n grafica de la jerarqu a del c digo Actualmente est solo disponible en H TML a INCLUDE_GRAPH generar un gr fico por cada archivo documen tado que incluya al menos un archivo m s Esta caracter stica est disponible s lo para HTML y RTF a CALL_GRAPH generar un gr fico por cada funci n sus llamadas y las llamadas a sta As mismo si CALLER_GRAPH est en YES se crear n los gr ficos mostrando por quien son llamadas las funciones CALLER GRAPH generar gr ficos que indica las funciones llamadas por la funci n documentada a COLLABORATION_GRAPEH generar un gr fico por cada clase do cumentada y estructura que muestre las relaciones de uso con otras estructuras Tambi n se puede utilizar la sintaxis de dot para generar un gr fico Los comandos espec ficos de dot deben estar entre los comandos dot y Xenddot 12 Generaci n autom tica de links La mayor a de los sistemas de documentaci n tienen una secci n espe cial see also vea tambi n donde pueden insertarse links a otras par tes de la documentaci n Adem s de que Doxygen posee un comando para comenzar una secci n as vea sa permite colocar esta clase de links en caulquier parte de la documentaci n Para la
10. a breve descripci n del elemento e bug Descripci n de un bug e cond lt sec gt Comienza una secci n condicional e date Incluye la fecha e deprecated Comienza un p rrafo desaprobado e lelse Cl usula adicional al comando Nif e lelseif lt sec gt Cl usula adicional al comando Acond e lendcond Finaliza una secci n condicional e lendif Finaliza una cl usula Nif e lexception lt e gt Comienza una descripci n de la excepci n para e e if lt sec gt Comienza una secci n condicional e lifnot lt sec gt Comienza una secci n condicional e linvariant Comienza una decripci n de un invariant e note Comienza un p rrafo de notas e par t Comienza un p rrafo con un t tulo opcional t e param lt p gt Comienza una descripci n del par metro p e post Comienza una descripci n de una post condici n e pre Comienza una descripci n de una pre condici n e lremarks Comienza un p rrafos de observaciones e return Comienza una descripci n de valores de retorno e lretval lt f gt Describe el valor de retorno de una funci n f e Isa ref Comienza un p rrafo See Also e see ref Equivalente a Asa e since Describe desde cuando una entidad estuvo disponible e test Comienza un p rrafo de descripci n test case e throw lt e gt Equivalente a excepci n e todo Comienza un p rrafo To Do e version Comienza un p rrafo donde puede
11. a es recomendable evitarstos comandos a menos que otros requerimientos lo fuercen Los comandos estructurales como todos los otros comandos comienzan con un backslash 1 o un arroba Para documentar una funci n global en C typedef enum o definici n del preprocesador primero debe documentar el archivo que lo contiene usual menteste ser un archivo header 9 Listas Doxygen provee varias maneras de crear listas de tems 9 1 Usando signos menos Colocando una cantidad de signos menos alineados en una columna al principio de la l nea generar n autom ticamente una lista Las listas nuricas tambien pueden ser generadasusando un signo menos seguido por un s mbolo numeral Es posible anidar listas indentando los tems Si utiliza tabs para la indentaci n dentro de listas por favor aseg rese que TAB_SIZE en el archivo de configuraci n tenga puesto el valor correcto Puede finalizar una lista comenzando un nuevo p rrafo o colocando un punto en una l nea vac a en el mismo nivel de indentaci n que la lista que desea terminar Veamos un ejemplo Texto anterior a la lista x item lista 1 sub item 1 sub sub item 1 k sub sub item 2 13 El punto de arriba significa que termina la lista de sub sub itens Mas texto del primer sub item El punto de arriba termina la lista de sub items Mas texto para el primer item de la lista sub item 2 sub item 3 list item 2 Mas texto
12. ca y sencilla Para peque os proyectos de pocos C C fuentes y headers puede dejar la tag INPUT vac a y doxygen buscar por fuentes en el directorio actual Si tiene un proyecto mas grande debe asignar los directorios o directorio ra z a la tag INPUT y agregar uno o mas patrones de archivos c h etc Ja la tagFILE PATTERNS S lo los archivos que coinciden con estos patrones ser n analizados Para un an lisis recursivo de un rbol de fuentes la tagRECURSIVE debe tener valor YES 5 Generando la documentaci n Para generar la documentaci n debe ingresar doxygen configfile Dependiendo de sus opciones doxygen crear los directorios html rtf latex xml y o man El directorio de salida por defecto es en el que doxygen se ha iniciado El directorio raiz en el cual se escribe la salida de doxygen puede modificarse usando OUTPUT_DIRECTORY El directorio especifico de formato dentro del directorio de salida puede ser seleccionado usando las HTML_OUTPUT RTF_OUTPUT LATEX_OUTPUT XML_OUTPUT y MAN_OUTPUT tags del archivo de configuraci n 5 1 Salida HTML La documentaci n HTML generada puede verse apuntando un browser html al archivo index html en el directorio html Para mejores resultados es mejor utilizar un browser con soporte para CSS Algunas caracter sticas como GENERATE TREEVIEW requieren de un browser con soporte para DHTML y Javascript Si tiene planeado usar el buscador tag SEARCHEN GINE debe ver la sal
13. cumentaci n mas legible Los links son creados para palabras que corresponden a clases documen tadas a menos que la palabra es precedida por en este caso la palabra no ser enlazada y el signo ser eliminado Los links a miembros son creados cuando se encuentran ciertos patrones en el texto Los marcadores HTML que est n en la documentaci n son interpretados y transformados en equivalente 7 Bloques especiales de documentaci n Es un bloque de documentaci n de C o C con algunas marcas adi cionales as doxygen puede reconocerlo y generar su documentaci n Para cada tem del c digo existen dos a veces tres tipos de descripcio nes que juntas forman la documentaci n una descripci n brief breve de una l nea y una descripci n detailed detallada mas extensa Para todos y funciones tambin existe una descripci n llamada in body en cuerpo que consiste en la concatenaci n de todos los bloques de documentaci n encon trados en el cuerpo de la funci n Existen varias formas de marcar un bloque de comentario como una descripci n detallada JavaDocs alternativa es usar un bloque de al menos dos lineas de comen tarios de C donde cada l nea comienza con un o adicional comentarios o bien comentarios Para aquellos a quienes desean comentarios mas visibles en la documen taci n pueden utilizar paaa aaao k kk kkk kkk kkk kkk kk comentarios EEEE E
14. externo y su documentaci n tiene derechos de autor de otra persona tal vez sea mejor o incluso necesario referenciarlo en lugar de incluir una copia del mismo con la documentaci n de su proyecto Cuando el autor proh be la redistribuci n esto es necesario Si el autor exige el cumplimiento de alguna condici n de licencia como condici n de redistribuci n y usted no quiere que se obligan a cumplir con esas condiciones en referencia a su copia de su documentaci n es preferible a que se incluya una copia Si se aplican algunas de las razones anteriores puede utilizar el me canismo de archivo de marcadores tag file de doxygen Un tag file es una representaci n compacta de las entidades encontradas en las fuentes externas Doxygen puede leer y generar tag files Para generar un tag file debe poner el nombre de un tag file a conti nuaci n de la opci n GENERATE_TAGFILE en el archivo de confi guraci n Para combinar la salida de uno o mas proyectos externos con el propio debe especificar el nombre de los tag files a continuaci n de la opci n TAGFILES en el archivo de configuraci n 22 Un tag file no contiene informaci n sobre d nde se encuentra la docu mentaci n externa sto podr a ser un directorio o una URL Entonces cuandos e incluye un tag file debe especificar el lugar en que se en cuentran Existen dos formas de hacer esto e En tiempo de configuraci n S lo asigne el lugar de salida al tag file espec
15. h configure Para conocer todas las opciones para usar el configure ejecute configure help Compile el programa ejecutando make El programa deber a compilar sin problemas y tres binarios deber an crearse en el directorio bin de la distribuci n Opcional Generar el manual del usuario ejecutando make docs Luego de compilar las fuentes ejecute un make install para instalar doxy gen 3 Comenzar El ejecutable doxygen es el programa principal que analiza el c digo y genera la documentaci n El ejecutable doxytag es necesario solo si desea generar referencias a documentaci n externa de la que no tiene las fuentes De manera opcional puede ser usado el ejecutable doxywizard que es una interfaz grafica para editar el archivo de configuraci n El siguiente gr fico muestra la relaci n entre las herramientas y el flujo de informaci n entre ellas FEA Doxywizard Your application custom output rea x doxmlparser lib generate edit pa XML files o p LA H Config file Doxyfile A make ps postscript HH e A Latex files poa read generate update m gt l Makefile make pdf PDF s seed po ources Doxygen m e H
16. ida html via un web server que soporte PHP ej apache con el modulo PHP instalado 5 2 Salida BT X La documentaci n latex generada debe ser compilada anteriormente por un compilador latex Para simplificar el proceso de compilaci n doxygen crea un Makefile dentro del directorio latex Los contenidos del Makefile van a depender de las opciones de USE_PDFLATEX si est deshabilitado tipeando make en el directorio latex generar un archivo dvi llamado ref man dvi Este archivo puede verse usando xdvi o convertirlo a PostScript refman ps tipeando make ps esta acci n requiere la herramienta dvips Tambi n es posible convertir los archivos a PDF si tiene instalado el int r prete de ghostscript con el comando make pdf o make pdf_2on1 Para obte ner mejores resultados en la salida PDF deberia setear los tags PDF_HYPERLINKS y USE_PDFLATEX en yes En este caso el Makefile contendra s lo el destino para construir refman pdf directamente 5 3 Salida RTF Doxygen combina la salida RTF a un nico archivo llamado refman rtf Este archivo es optimizado para importar desde Microsoft Word Cierta informaci n es codificada usando campos Para mostrar el valor real usted necesita seleccionar todo Edit Select All y luego alternar campos 5 4 Salida XML La salida XML consiste de dump estructurado de informaci n reunida por doxygen Cada componente tiene su propio archivo XML y tambn existe un archivo index llamado index xml Un a
17. ificado en la opci n TAGFILES Si usa un path realativo debe ser relativo respecto del directorio donde la salida HTML de su proyecto es generada e Luego de la compilaci n Si no asigna un lugar a el tag file doxy gen generar dummy links para todas las referencias HTML ex ternas Tambi n generar un script de perl llamado installdox en el directorio de salida HTML ste script debe ejecutarse para re emplazar los dummy links por links reales para todos los archivos HTML generados En algunos excepcionales casos puede tener la documentaci n gene rada por doxygen pero no los fuentes ni los tag files En este caso puede usar la herramienta doxytag para extraer un tag file de los HTML ge nerados Otro caso en el que debe usar doxytag es si desea crear un tag file para la documentaci n Qt La herramienta doxytag depende de la estructura particular de la sa lida generada y de algunos marcadores especiales que son generados por doxygen Ya que sta clase de extracci n es fr gil y susceptible a errores es recomendable que sea usada en caso de que no exista otra alternativa 23 15 Comandos Especiales Todos los comandos en la documentaci n comienzan con un backslash Vo un arroba 9 Algunos comandos tienen uno o mas argumentos Cada argumento tiene un cierto rango e si lt gt entonces el argumento es una sola palabra e si entonces el argumento se extiende hasta el final de la l nea e si entonces el argumento
18. ingresar la ver si n e warning Comienza un p rrafo para mensajes de alerta e Axrefitem lt k gt h Crea un p rrafo cross referenced 27 15 4 Indicadores de links e laddindex t Agrega t al index de ATEX e lanchor w Coloca un anchor invisible w en el documento e lendlink Finaliza un link e llink lt n gt Crea un link a n con texto especificado por el usuario ref lt n gt t Crea una referencia a n con texto t e isubpage lt n gt t Crea una sub p gina de nombre n e section lt 1 gt t Crea una secci n en una p gina con etiqueta 1 y t tulo t e Isubsection lt 1 gt t Crea una sub secci n en una p gina con etiqueta 1 y t tulo t e paragraph lt n gt t Crea un p rrafo en una p gina con etique ta 1 y t tulo t 28 15 5 Bloques especiales de documentaci n en VHDL Para VHDL un comentario comienza normalmente con Doxygen extraer los comentarios que comiencen con Existen solo dos tipos de bloques de comentarios en VHDL de una l nea que re presenta una descripci n breve y de m s de una linea hay que repetir 1 por cada l nea representa una descripci n detallada Los comentarios siempre se ubican delante del tem a documentar con una excepci n para puertos el comentario puede tambi n ir despu s del tem y luego es tratado como una descripci n breve del puerto Aqu sigue un ejemplo de un archivo en VHDL con comentarios Doxy gen
19. ment y se expandir de la siguiente manera This is a lt b gt bold lt em gt and lt em gt Emphasized lt b gt text fragment 21 14 Links a documentaci n externa Si su proyecto depende de librer as externas o herramientas hay varias razones por las cuales no inclu r todas la fuentes en cada pasada de doxygen lt gt Espacio en disco Alguna documentaci n puede estar dis ponible fuera del directorio de salida de doxygen por ejemplo en alg n lugar de la web Si lo desea puede vincular a estas p ginas en lugar de generar la documentaci n en su directorio local de salida Velocidad de Compilaci n Los proyectos exter nos suelen tener una frecuencia de actualizaci n diferente a las de su propio proyecto No tiene mucho sentido dejar que doxygen analice las fuentes de stos proyectos externos una y otra vez in cluso si nada ha cambiado Memoria Para rboles muy grandes de c digo fuente permitir que doxygen analice todas las fuentes puede tomar demasiado de la memoria del sistema Dividiendo las fuentes en varios packages las fuentes de un paquete puede ser analizadas por doxygen mientras que todos los otros packa ges que dependen de este paquete estan linkeados externamente Esto ahorra una gran cantidad de memoria Disponibilidad Pa ra algunos proyectos que est n documentados con doxygen las fuentes pueden simplemente no estar disponibles Cuestiones de derecho de autor Si el paquete
20. mulas no num ricas en l neas separadas deben colocarse entre los comandos Xf y f por ejemplo 16 NEL I_2 left Mint_10 T Apsi t left u a t int_ gamma t a frac d theta k theta t int_ a theta c xi u_t xi t d xi right dt right NE La salida se ver as 12 IT Lula t Sito ea Sa Eule t de di Las f rmulas u otros elementos de que no son del ambiente matem ti co pueden ser especificados usando el comando fenvironment donde environment es el nombre del ambiente de el fin del comando es f Veamos un ejemplo equation array f eqnarray g amp amp frac Gm_2 r 2 amp amp frac 6 673 times 10 11 mbox m 3 mbox kg 1 mbox s 2 5 9736 times 10 24 mbox kg H 6371 01 mbox km 2 amp amp I 82066032N mbox m s 2 NE La salida se ver as G g 77 6 673x10 1 m3 kg s 2 5 9736x10 4 kg 6371 01 km 9 82066032 m s 17 11 Gr ficos y diagramas Doxygen puede crear gr ficos generados por la herramienta dot de Graph viz http www graphviz org La generaci n de gr ficos en Doxygen gene ralmente se realiza automaticamente basada en las opciones del archivo de configuraci n Estas opciones con excepci n de DOT_PATH pueden tener los valores YES o NO Estas son opciones globales para el proyecto Los gr ficos s lo ser n generados si la herramienta dot est instalada y la opci n HAV
21. n de los miembros de lante de la definici n incluyendo funciones globales De sta manera la do cumentaci n puede ser ubicada en el archivo fuente en lugar del archivo header Esto permite que el archivo de headers quede compacto y permite a los implementadotes de los miembros un acceso mas directo a la documen taci n Tambien las descripciones breves pueden situarse antes de la declaraci n y la descripci n detallada antes de la definici n del miembro stos bloques solo pueden ser utilizados para documentar miembros o par metros no pueden ser usados para documentar archivos clases unio nes estructuras grupos namespaces y enums Por lo tanto los comandos estructurales mencionados en la pr xima secci n como class son ignorados dentro de stos bloques de comentarios 12 8 Documentaci n en otros sitios Hasta ahora hemos asumido que los bloques de documentaci n est n siempre ubicados al frente de una declaraci n o definici n de un archivo clase o namespace o delante o detr s de un miembro Puede haber ocasiones en las que se desee comentar en otros sitios Doxygen le permite colocar bloques de documentaci n pr cticamente en cualquier sitio la excepci n es dentro del cuerpo de una funci n o dentro de un bloque de comentarios normal en C style Lo que se necesita es un comando estructural dentro del bloque de do cumentaci n lo que conlleva a algunas duplicaciones de informaci n Por lo tanto en la pr ctic
22. rchivo XSLT llamado combine xslt tambin es generado y puede ser usado para combinar todos los archivos XML a un nico archivo Doxygen tambin genera dos archivos esquema XML index xsd para el archivo index und xsd para los archivos de componentes Este archivo de esquemas describe los posibles elementos sus atributos y como est n estructurados 5 5 Salida Man las paginas de manual generadas pueden verse utilizando el programa man Debe asegurarse que el directorio man este en el man path ver la variable de entorno MANPATH 6 Documentando el c digo Si la opci n EXTRACT_ALL tiene el valor NO en el archivo de confi guraci n opci n por defecto doxygen s lo generar documentaci n para miembros documentados archivos clases etc Para documentar hay dos opciones Colocar un bloque especial de documentaci n delante de la declaraci n o definici n de los miembros clases etc Colocar un bloque especial en alg n otro lugar otro archivo u otra ubicaci n y poner un comando estructural en el bloque de documen taci n Un comando estructural enlaza un bloque de documentaci n a una cierta entidad que puede ser documentada Los archivos solo pueden ser documentados de la segunda forma Las fun ciones variables typedefs defines no necesitan un comandodas las l neas vac as resultantes son tratadas como separadores de p rrafos Esto evita que se deban agregar comandos de nuevo p rrafo para lograr una do
23. read SS read generate A e Man pages Custom headers F footers e O U uae AAA images Windows only i i import doc i La refman rf Es MS Word o i generate 1 i i i A a end HTML Help Worksh Bira elp Worksho Doxytag LA pages p y parse f i H i P ARS O SA Figura 1 flujo de informacion 4 Crear un archivo de configuraci n Doxygen usa un archivo de configuraci n para determinar todas sus op ciones Cada proyecto deber a tener su propio archivo de configuraci n Para simplificar la creaci n de este archivo doxygen puede crear uno con el comando doxygen g configfile donde lt configfile gt es el nombre del archivo de configuraci n si se omite el nombre del archivo se crear uno llamado doxyfile Si ya existe un archivo con el mismo nombre doxygen renombrar el actual a lt configfile gt bak antes de generar el nuevo El archivo de configuraci n tiene un formato similar al de un Makefile consiste en un numero de asignaciones tags de la forma TAGNAME VALUE Si comienza a usar doxygen para un proyecto existente puede hacerse una idea de como es la estructura y de como resultar la documentaci n poniendo la tag EXTRACT_ALL YES Si no desea editar el archivo de configuraci n con un editor de texto puede usar dorywizard una interfaz gr fica que puede crear leer y editar los archivos de configuraci n del dorygen de manera gr fi
24. rupos de miembros Si un compuesto clase o archivo tiene muchos miembros es usualmente deseado agruparlos Un grupo de miembros es definido de la siguiente manera I NA 0y bloque 15 Antes de abrir un marcador de bloque puede colocarse un bloque de comen tarios separado Este bloque debe contener el comando name o name y se utiliza para especificar el encabezado del grupo No est permitido el anidamiento de grupos de miembros 10 3 Subpaginar La informaci n puede ser agrupada en p ginas usando los comandos page y mainpage Normalmente esto resulta en una lista plana de p ginas donde la p gina main es la primera en la lista 10 4 Inclu r f rmulas Doxygen permite agregar f rmulas a la salida funciona solamente para las salidas y HTML Son necesarias las siguientes herramientas IAT X el compilador de ATEX a Dvips Una herramienta para convertir archivos DVI a archivos PostS cript Gs el intrprete GhostScript para convertir archivos PostScript a bit maps Existen tres formas de incluir f rmulas en la documentaci n 1 Utilizando f rmulas que aparecen en el texto en una l nea stas f r mulas deben colocarse entre un par de comandos f como por ejemplo La distancia entre Mf x_1 y_1 Mf y f x_2 y_2 f es M Asqrt1i x_2x_1 72 y_2y_1 2H La salida se ver as La distancia entre x1 y1 y 2 Y2 es y 12221 yay1 2 F r
25. sma manera que se explica en la secci n anterior Para mayor claridad es recomendable utilizar los patrones 3 y 7 en ste caso 12 5 typedefs Los typedefs que involucran clases estructuras y uniones como ty pedef struct StructName TypeName crean un alias para StructName entonces se crear n links para StructName cuando StructName mismo o TypeName son encontrados 19 lt modifiers gt 13 Comandos Doxygen provee un gran n mero de comandos especiales comandos XML y comandos HTML que pueden ser usados para realzar o es tructurar la documentaci n dentro de un bloque de comentario Si por alguna raz n existe la necesidad de definir un nevo comando se puede utilizar una definicion ALIAS La definici n de un alias debe ser espe cificada en el archivo de configuraci n usando el tag de configuraci n ALIASES 13 1 Alias simples La forma mas simple de un alias es la sustituci n simple de la forma name value Por ejemplo ALIASES sideeffect MXpar Side Effects 1n esto permitir poner el comando Asideefect en la documentaci n que resultar en un p rrafo definido por el usuario con encabezado Side Effects N tese que puede colocar in en la parte del valor de un alias para insertar una nueva l nea 13 2 Alias con argumentos Los alias pueden tener uno o m s argumentos En la definici n del alias se necesitan un n mero espec fico de argumentos entre llaves En la parte del valor de la definici n se p
26. ueden colocar marcadores Ax donde x representa el n mero de argumento empezando por 1 Por ejemplo ALIASES 141 MXref M1 Dentro de un bloque de comentarios See l SomeClass for more information Os See XMref SomeClass for more information ALIASES 141 Mref M1 20 ALIASES 1 2 ref M1 2 See l SomeClass Some Text for more information Dentro de un bloque de comentarios se expander a See ref SomeClass Some Text for more information donde el comando con un s lo argumento seguir funcionando como se muestra anteriormente Alias tambi n pueden expresarse en t rminos de otros alias Ejemplo un nuevo comando reminder puede ser expresado como xrefitem por un comando intermediario xreflist ALIASES xreflist13 Mxrefitem M1 NUN2QN AMABA N ALIASES reminder Mxreflistfreminders Reminder Reminders Para alias con mas de un argumento se utliza la coma como separador Si se desea poner una coma dentro del comando necesitar usar un backslash ejemplo WMSomeClass Some text with an escaped comma 13 3 Anidando comandos Puede utilizar comandos como argumentos de alias incluyendo coman dos definidos utilizando alias ej ALIASES Bold11 lt b gt backslash 1 lt b gt ALIASES EmphX1 lt em gt backslash 1 lt em gt dentro de un bloque de comentarios This is a backslash Bold bold backslash Emphtand Emphasized text frag
27. usando lt nombre gt mas de una vez no resultara en un warning sino en un grupo con la documenta cion combinada y el primer titulo que encuentre en alguno de los comandos El titulo es opcional por lo tanto este comando tam bien puede ser utilizado para agregar un numero de entidades a un grupo existente usando Q y Q icallgraph Cuando este comando es colocado en un bloque de comentarios de una funcion y HAVE DOT esta en Yes doxygen generara un grafico de llamadas para esa funcion El grafico sera generado a pesar del valor que tenga CALL_GRAPH lcallergraph Cuando este comando es colocado en un bloque de comentarios de una funcion y HAVE_DOT esta en Yes doxy gen generara un grafico de llamador de funciones para esa fun cion El grafico sera generado a pesar del valor que tenga CA LLER GRAPH class lt nombre gt lt archivo header gt lt nombre header gt Indica que un bloque de comentarios contiene documentacion pa ra una clase con el nombre lt nombre gt def lt nombre gt Indica que un bloque de comentarios contiene documentacion para un macro define defgroup lt 1 gt lt t gt Define un grupo de m dulo con etiqueta 1 y t tulo t enum lt nombre gt Indica que un bloque de comentarios contie ne documentacion para una enumeracion con nombre lt nombre gt lexample lt nombre archivo gt Indica que un bloque de comen tarios contiene documentacion de un ejemplo de codigo fuente El nombre del archivo fuente
28. use este comando a menos que sea absolutamente necesario ya que lleva a la duplicacion de informacion y en consecuencia a errores hideinitializer Oculta el valor por defecto de define Xingroup lt 11 gt lt 12 gt Agrega documentacion al grupo 11 Mul tiples grupos pueden ser usados Vinterface lt n gt Bloque de documentaci n para la interface n Vinternal Todo el texto a continuaci n es sustra do hasta el final del bloque de comentarios mainpage t El bloque de documentaci n del main o index name header Bloque de documentaci n de grupo de miem bros nosubgrouping Desactiva el subagrupamiento subgrouping loverload s Utilizado para documentar una funcion overloaded con firma s package lt n gt Un bloque de documentaci n para el package n page lt n gt t Indica un bloque de documentaci n de un grupo de p gina con etiqueta n y t tulo t Ashowinitializer Muestra el valor por defecto de define struct lt n gt Bloque de documentaci n para una estructura n typedef t Bloque de documentaci n para un typedef t union lt n gt Bloque de documentaci n para la union n Ivar v Bloque de documentaci n para la variable v weakgroup lt n gt Equivalente a laddtogroup pero tiene menor prioridad en la resoluci n de conflictos de grupos 26 15 3 Indicadores de secci n e lattention Comienza un p rrafo de Atenci n e lauthor loa Incluye la lista de autores loa e Wbrief Un
Download Pdf Manuals
Related Search