TODOPIC

Microcontroladores PIC => * PROYECTOS * => Mensaje iniciado por: RedPic en 25 de Octubre de 2007, 15:16:18

Título: Documentar los Proyectos : Doxygen
Publicado por: RedPic en 25 de Octubre de 2007, 15:16:18
Después de dar varias vueltas por el foro sin acabar de decidirme dónde colocar este nuevo hilo. Al final me he decidido por el de Proyectos ya que su contenido tiene mucho que ver con ellos, aunque sea en general con todos los proyectos y no con ninguno de ellos en concreto.

Hay Proyectos y proyectitos. Los Proyectos, con mayúsculas, profesionales o no, pero complejos, largos y/o farragosos son difíciles de mantener vivos conforme pasa el tiempo. ¿Quien no se ha enfrentado a un código fuente propio tras algunos meses, y no digamos años, y no ha entendido absolutamente nada de lo que ese código hacía, ni cómo lo hacía ni por qué hacía lo que hacía?

La memoria de nosotros los programadores es una memoria RAM volátil a corto plazo.

Algoritmos evidentes en si mismos, implementados por cualquiera de nosotros hoy, no es mañana inteligible no a otros programadores, sino ni siquiera por nosotros mismos. Nombres de variables o funciones, que hoy llamamos int2string y mañana int8_to_str, procedimientos, parámetros de entrada o salida, defines, includes ... etc.

La solución para fijar en la memoria todo este galimatías esta en : documentar.

Escribir sistemáticamente todo lo relevante a nuestro proyecto, las descripciones de cómo y por qué tomamos esta o aquella decisión, para qué sirve y cómo se utiliza esta función o aquél parámetro.

Y en nuestra ayuda viene Doxygen, un programa con licencia GNU (o sea: que podemos utilizar alegre y confiadamente sin que nadie venga a sobresaltarnos con demandas, multas, etc.).

Doxygen es una Source code documentation generator tool Herramienta Generadora de Documentación para Código Fuente. Su página Web es Doxygen (http://www.stack.nl/~dimitri/doxygen/) y en ella está disponible todo lo necesario para su uso y disfrute.

Os lo recomiendo muy encarecidamente, en mi trabajo lo utilizamos por norma y los resultados son espectaculares: Todos los programadores entendemos lo que hacen los otros, nosotros mismos sabemos qué hicimos y como utilizarlo meses después de haberlo olvidado completamente. Y además su documentación generada nos sirve como referencia constante para usarla a diario.

Y por si fuera poco nos obliga también a describir qué estamos haciendo en el momento de hacerlo por lo que nos fuerza a trabajar de forma clara y explicable de cara a los demás.

Un Ejemplo:

Hace unos días he posteado un pequeño proyecto en este mismo foro titulado: El RS485, un Relé en la lejanía: Hardware y Software (http://www.todopic.com.ar/foros/index.php?topic=19057.0). En él se publicaba un código fuente que comenzaba con un curioso párrafo de comentario:

Código: C++
  1. /** \file firmware_iRELE485-628.c
  2.  * \brief Este fichero contiene el cuerpo principal del Firmware del\n
  3.  * dispositivo auxiliar satélite de la iACD V1.0.4. denominado iRELE485-628
  4.  *
  5.  * Integra todos los subsistemas y funciones implementados.\n
  6.  * Source para el compilador CCS C v.3.242
  7.  *
  8.  * Microprocesador : <b>16F628A</b> (18 pines PDIP) \n\n
  9.  * Fuses utilizados: \n
  10.  * \li <b>INTRC</b> Internal RC Osc
  11.  * \li <b>MCLR</b> Master Clear pin enabled
  12.  * \li <b>NOWDT</b> No Watch Dog Timer
  13.  * \li <b>NOPROTECT</b> Code not protected from reading
  14.  * \li <b>NOPUT</b> No Power Up Timer
  15.  * \li <b>NOBROWNOUT</b> No brownout reset
  16.  * \li <b>NOLVP</b> No low voltage prgming, B3(PIC16)
  17.  * \li <b>NOCPD</b> No EE protection
  18.  *
  19.  * \author Diego Márquez García-Cuervo \n
  20.  * <http://picmania.garcia-cuervo.net>
  21.  *
  22.  * \version 1.0.0.A
  23.  */

Es cómo se comenta, cara a Doxygen , el contenido de un fichero fuente. Es hacer lo que todos hacemos al inicio de un fichero .C pero teniendo en cuenta lo que Doxygen va a necesitar.

El resto del código fuente continúa del mismo modo comentando variables, defines y funciones.

Es solo un ejemplo, no está documentado al nivel de los que tengo que realizar en mi vida profesional en los que la profundidad de la descripción es mucho mayor pero bien vale como introducción.

Al procesar con Doxygen estos códigos fuentes se generan, en HTML por ejemplo, todas las referencias cruzadas, índices y descripciones detalladas que hagan falta.

El Código Fuente (http://picmania.garcia-cuervo.net/recursos/firmware_irele485-628.c) del ejemplo procesado con este script DOX (http://picmania.garcia-cuervo.net/recursos/firmware_irele485-628.dox) (no os asustéis, tiene un Expert en español para generarlo) generó esta Documentación del iRele485-628 (http://picmania.garcia-cuervo.net/ejdox/main.html) que deseo que visitéis para que veáis los resultados.

Ea, mañana más.  :mrgreen:
 
Título: Re: Documentar los Proyectos : Doxygen
Publicado por: Nocturno en 29 de Octubre de 2007, 14:17:52
Yo tuve la oportunidad de ver la documentación de tu proyecto del iACD, Diego, y quedé maravillado con la herramienta.
Aún así, siempre me ha dado pereza escribir tanto, limitando mis comentarios a simples líneas encima, enmedio o bajo las funciones que considero que lo necesiten.
Pero es cierto, el paso del tiempo y el ron, y la degradación de las neuronas hacen que luego sea complicadísimo ponerlo en pie.
Le daré una oportunidad a esa herramienta.

JCC40, ¿a qué software te refieres?
Título: Re: Documentar los Proyectos : Doxygen
Publicado por: PalitroqueZ en 29 de Octubre de 2007, 19:39:16
yo uso uno muy práctico y que reconoce multiples lenguajes (reconoce bucles)  8)

Notepad++ (http://notepad-plus.sourceforge.net/es/site.htm)

no hará muchas cosas, pero me sirve jeje
Título: Re: Documentar los Proyectos : Doxygen
Publicado por: SavageChicken en 03 de Noviembre de 2007, 10:57:20
Cita de: RedPic en 25 de Octubre de 2007, 15:16:18
La memoria de nosotros los programadores es una memoria RAM volátil a corto plazo.

Algoritmos evidentes en si mismos, implementados por cualquiera de nosotros hoy, no es mañana inteligible no a otros programadores, sino ni siquiera por nosotros mismos. Nombres de variables o funciones, que hoy llamamos int2string y mañana int8_to_str, procedimientos, parámetros de entrada o salida, defines, includes ... etc.

La solución para fijar en la memoria todo este galimatías esta en : documentar.

Es totalmente cierto, yo en particular uso assembler y a pesar de no trabajar con erramientas externas para documentar, tengo el hábito de comentar todas las líneas de código, de manera que luego pueda entender que hice y por qué está ahí esa línea, todas la variables, bucles y funciones tienen un comentario lo más claro y consiso posible.
Eso me ha permitido retomar proyectos dejados largo tiempo en espera sin mayores problemas.
Es cierto que no es muy agradable al comienzo, pero incluso al momento de escribir el código ayuda a entender lo que estás haciendo.
Siempre comienzo haciendo una lista, en formato de comentario, con las cosas que debe hacer el programa y luego esa misma lista se transforma en los comentarios de las funciones que se fueron implementando.

Es una práctica muy sana.

Salud  8)
Título: Re: Documentar los Proyectos : Doxygen
Publicado por: stk500 en 06 de Noviembre de 2007, 02:47:07
Doxigen lo encuentros muy interesante, pero el miedo que me da es integrarlo con el WinAVR, aqui espero algunos comentarios y consejo al respecto ya que estoy siguiendo este tema de Redpic
Título: Re: Documentar los Proyectos : Doxygen
Publicado por: Nocturno en 07 de Marzo de 2008, 17:40:13
Acabo de encontrar este proyecto documentado con Doxygen y se me cae la baba. Qué lástima que yo sea tan indisciplinado para esto.

Po3030k Device Driver for dsPIC33 (http://stephane.magnenat.net/molole-doc/index.html)
Título: Re: Documentar los Proyectos : Doxygen
Publicado por: reiniertl en 07 de Marzo de 2008, 20:48:58
No cabe dudas que me voy a instalar esa cosa, o conseguírmela o lo que haga falta para usarla. Me encantan los programas bien documentados, sobre todo porque no me cuesta mucho escribir cantidad ;-) y porque soy de los súper programadores que se acuestan hoy y mañana no saben que rayos han escrito. Como cuando te vas a la cama después de una buena curda y al otro día ni sabes que fue lo que hiciste la noche anterior.

Gracias Diego por tan buen aporte.

Saludos
Reinier
Título: Re: Documentar los Proyectos : Doxygen
Publicado por: RedPic en 07 de Marzo de 2008, 22:46:35
Venga, todo sea por hacer las cosas mejor. En mi trabajo me lo exigen, es natural ya que mi código fuente puede mañana ser tocado por algún otro programador y tiene que tener disponible la información. Pero ahora estoy cogiéndole el gusto y ya lo coloco las etiquetas Doxygen a todo lo que hago, sea C, Java o Delphi.  :mrgreen:
Título: Re: Documentar los Proyectos : Doxygen
Publicado por: Nocturno en 24 de Marzo de 2008, 03:06:24
Don Diego, gracias por haberme puesto en el camino.

En el proyecto que estoy haciendo me he obligado a usar esta herramienta y no puedo estar más contento con los resultados.

Gracias  :-/
Título: Re: Documentar los Proyectos : Doxygen
Publicado por: RedPic en 24 de Marzo de 2008, 03:36:20
Cita de: Nocturno en 24 de Marzo de 2008, 03:06:24
Don Diego, gracias por haberme puesto en el camino.

En el proyecto que estoy haciendo me he obligado a usar esta herramienta y no puedo estar más contento con los resultados.

Gracias  :-/

A mandar, que pa'eso estamos.  :mrgreen:
Título: Re: Documentar los Proyectos : Doxygen
Publicado por: damago en 24 de Marzo de 2008, 07:51:13
Vaya, como dice Nocturno, yo tambien estoy acostumbrado a comentar sobre el propio codigo lo que considero necesario. Ademas en mi trabajo mi codigo lo toco solo yo (hasta ahora de momento jeje). Es mas, tanto comentar sobre el propio codigo fuente no me acaba de gustar (me gustar ver mas codigo y menos comentarios en los archivos .c).

Por otra parte, los resultados que he visto en tu ejemplo RedPic me han gustado mucho, y es una gozada tener todo tan bien documentado, para ti o para quien venga despues.

El caso es que tambien voy a probarlo, para el programa que llevo entre manos ahora, a ver que tal la experiencia.
Conoces alguna utilidad para crear otro archivo igual que el *.c o *.h  documentado pero sin todo lo comentado par el doxygen? (bueno eso lo podriamos hacer nosotros mismos con un pequeño programita....pero si conoces algo..... debe ser cosa de acostumbrarse, pero no me acaba de gustar revisar un codigo con mas comentarios que codigo (si lo entiendo claro)).

Gracias por el enlace RedPic, creo que es una muy buena herramienta.

Un saludo.
Título: Re: Documentar los Proyectos : Doxygen
Publicado por: samshiel_pic en 24 de Marzo de 2008, 17:37:32
Hola compañeros que tal va todo??? me ha gustado mucho el Doxygen y me va ha ser muy util pero me veo en un pequeño problema de entendimiento entre él y yo, porque no se como se utiliza. :mrgreen: :mrgreen:
Haber si me echais una manita  :D :D
Título: Re: Documentar los Proyectos : Doxygen
Publicado por: migsantiago en 24 de Marzo de 2008, 19:11:55
- Descargandooo -

Un tutorial por favoooorrr  DIegoooo amiiggooooo  :D
Título: Re: Documentar los Proyectos : Doxygen
Publicado por: Nocturno en 25 de Marzo de 2008, 03:12:55
Instálalo, Migsantiago. Tiene una documentación extraordinaria y muy fácil de entender, como no podía ser de otra manera tratándose de una herramienta para documentar  :D
Título: Re: Documentar los Proyectos : Doxygen
Publicado por: migsantiago en 25 de Marzo de 2008, 11:57:47
Bueno.






 :D
Título: Re: Documentar los Proyectos : Doxygen
Publicado por: 5GTT en 28 de Marzo de 2008, 22:54:28
Yo tambien lo voy a probar, para cosas de casa su utilidad es limitada, pero para proyectos de verdad... creo que no tiene precio.

Habia visto cosas parecidas para proyectos de instalaciones industriales, no sabia que existieran para software.
Título: Re: Documentar los Proyectos : Doxygen
Publicado por: RedPic en 29 de Marzo de 2008, 08:50:48
Cita de: migsantiago en 24 de Marzo de 2008, 19:11:55
- Descargandooo -

Un tutorial por favoooorrr  DIegoooo amiiggooooo  :D

Miguel Santiago: En cuanto tenga un hueco, ahora estoy de trabajo hasta mas allá de lo razonable, te pongo un hiper-ejemplo: Un programa completo "doxygenado" y la documentación que se genera. De todas formas el ejemplo mini lo tienes en el que puse en el primer post sobre el programa del 485.  :mrgreen:

Título: Re: Documentar los Proyectos : Doxygen
Publicado por: samshiel_pic en 27 de Abril de 2008, 11:20:05
Hola chicos que tal??
pues llevo ya un rato liado con el doxigen y no consigo los resultados que tienes tu diego no me llega a salir todo el codigo c, no me salen las mismas funciones, vamos que ni idea de que opciones tengo que utilizar para que me saga como a ustedes.
Os dejo los resultados para que veais lo que os digo.
Título: Re: Documentar los Proyectos : Doxygen
Publicado por: migsantiago en 27 de Abril de 2008, 23:31:03
Cita de: RedPic en 29 de Marzo de 2008, 08:50:48
Miguel Santiago: En cuanto tenga un hueco, ahora estoy de trabajo hasta mas allá de lo razonable, te pongo un hiper-ejemplo: Un programa completo "doxygenado" y la documentación que se genera. De todas formas el ejemplo mini lo tienes en el que puse en el primer post sobre el programa del 485.  :mrgreen:

Gracias Diego, si me gusta la aplicación talvez la use para documentar los programas para mi tesis.  :mrgreen:
Título: Re: Documentar los Proyectos : Doxygen
Publicado por: samshiel_pic en 30 de Abril de 2008, 15:10:39
Pues haber si a ti te va mejor que a mi migsantiago.

Os adjunto una imagen de lo generado por doxigen y es que no entiendo por que no me salen las lineas de introduccion que estan comprendidas entre el 00001 y el 00043. Pero es que no salen ninguna explicacion del programa en él.

No se haber si me podeis ayudar por que ni no tengo ni papa, jejejeje.

Título: Re: Documentar los Proyectos : Doxygen
Publicado por: migsantiago en 30 de Abril de 2008, 18:09:09
Hola

También veo que te está dando problemas con los acentos como en la palabra "estándar"  :?
Título: Re: Documentar los Proyectos : Doxygen
Publicado por: Nocturno en 01 de Mayo de 2008, 02:03:00
Paisano, es normal que no te salgan esas líneas, porque son las que contienen la información que Doxygen utiliza para generar la documentación automática.

Justo encima de ese código que has mostrado, ¿no tienes un link llamado "Ir a la documentación de este archivo."?

Respecto al tema de los acentos, tienes que tener codificación UTF-8 y Latin-1.
Creo que lo mejor será que adaptes un Doxyfile que funcione a tus necesidades. Si quieres prueba con el que yo utilicé en mi proyecto, al que tendrás que cambiar las rutas a los ficheros para que funcione con el tuyo.
Lo dejo adjunto
Título: Re: Documentar los Proyectos : Doxygen
Publicado por: samshiel_pic en 01 de Mayo de 2008, 13:36:04
Por fin ya esta bien!!!! que trabajito me ha costado jejejeje
Me gusta mucho este programa para documentar los proyectos, esta muy bien con esto no se olvidara para que era una parte de codigo al cabo de un tiempo. :D :D
Título: Re: Documentar los Proyectos : Doxygen
Publicado por: Suky en 20 de Mayo de 2009, 19:42:45
Cita de: Nocturno en 07 de Marzo de 2008, 17:40:13
Acabo de encontrar este proyecto documentado con Doxygen y se me cae la baba. Qué lástima que yo sea tan indisciplinado para esto.

Po3030k Device Driver for dsPIC33 (http://stephane.magnenat.net/molole-doc/index.html)

Realmente este software esta muy interesante. Alguien lo a trabajado? Como se podrá llegar a conseguir algo como lo que se muestra?
Título: Re: Documentar los Proyectos : Doxygen
Publicado por: Suky en 21 de Mayo de 2009, 03:19:31
Bueno, me puse a hacer algunas pruebas con este programita y adjunto un ejemplo. Realmente muy interesante!  :lol:
Seguramente alguien que ya ha trabajado con el me podrá aconsejar y/o corregir algo :wink:
Título: Re: Documentar los Proyectos : Doxygen
Publicado por: RedPic en 18 de Junio de 2010, 14:40:23
Reparado el link roto de este hilo (gracias Pájaro por el aviso) II