DaXHordes.org

Abro este hilo para discutir cómo podríamos incorporar documentación/comentarios al código. Sin ánimos de ofender, la forma en que lo hacíamos hasta ahora no me ha convencido del todo. Por ejemplo, muchos IDEs permiten ver la definición de la clase/método/atributo dejando el ratón encima, y así no se pueden ver los comentarios sobre el método. Además tal y como estaba planteado era incluso mejor tener la documentación en un fichero aparte. Estoy pensando seriamente en la opción de algo como JavaDoc (que alguien comentó anteriormente, no recuerdo ahora a quién).

Es establecer una forma y o bien alguien que quiera desarrollar una herramienta tipo javadoc.

O aquellos que no se vayan a involucrar a nivel de programación, que preparen la documentación si quieren.

yo creo que estaria bueno otro tipo de diagrama (el que hiciste es bueno) o mas comentarios en el codigo, estuve menos de 2 dias sin leer y has avanzado un monton y a la vez rediseñado muchas cosas, se me esta complicando para seguir el proyecto, ya que solo puedo leer el codigo y tratar de entender la idea.

tal vez mas comentarios o otro diagrama de clases (con atributos y metodos) podria ayudar, ademas de algun comentario a nivel general de que es lo que se pretende con cada clase. Aparecieron muchas clases nuevas y se me complica el 'que hacen" voy a empezar con las consultas en el hilo del codigo fuente.

yosoy_bostero escribió:yo creo que estaria bueno otro tipo de diagrama (el que hiciste es bueno) o mas comentarios en el codigo, estuve menos de 2 dias sin leer y has avanzado un monton y a la vez rediseñado muchas cosas, se me esta complicando para seguir el proyecto, ya que solo puedo leer el codigo y tratar de entender la idea.

Es lo que suele pasar en este tipo de proyectos compartidos. Siento no tener tiempo para poner más comentarios, pero espero que estos días me ponga a comentar lo que ya está hecho antes de seguir codificando más, que al final soy yo el que va a olvidar qué hace cada cosa

yosoy_bostero escribió:otro diagrama de clases (con atributos y metodos) podria ayudar

Es que los diagramas llevan tiempo. Si se pudiera encontrar alguna herramienta de análisis de código que lo haga automáticamente, sería mucho más sencillo, y se podrían poner anotaciones sobre dichos diagramas. Si sabéis de alguna para C++ (tampoco me he puesto a buscar, pero tiene que haber) pues lo comentáis por el hilo de herramientas.

yosoy_bostero escribió:Aparecieron muchas clases nuevas y se me complica el 'que hacen" voy a empezar con las consultas en el hilo del codigo fuente.

Sí, cuando quieras te resuelvo las dudas que tengas. Y sí, tengo que poner más comentarios, no hay ni uno Es que me he cebado con la codificación

Comento también los defines? Lo prefiero, si no te importa. La decisión final es tuya.

Edito: Y los métodos privados? Claro que éstos si encuentro como.

Reedito: Hecho. Busco paquete de generación de gráficos

Reedito de nuevo: Bueno, los gráficos me van a dar trabajo Bueno, los reportes son optativos, pero parece que hago algo

Cuanto más comentario, mejor, siempre que sigas la estructura que marca Doxygen (que es lo que estás usando, no?)

Saludos, gracias y ánimo

Si, si, Doxygen.

Gracias a ti. No veas como me lo paso. Comentando na más. Imagínate si codifico algo
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Ésto lo traigo de otro post, para no mezclar más.
-----------------------
Pues a comentar se ha dicho. Te importa que me encargue de generar la documentación? Es un botón sólo. Incluso se puede crear un script para que haga todo. Ya tengo configurado el doxygen, que por otro lado lo da todo(casi) hecho ya con la GUI. El script sería sólo comparar y escribir las órdenes. La doc está en html por defecto. Se podría subir a googlecode?

Estoy haciendo que guarde copias de los archivos .h, que quedarán con los comentarios de línea simple.
Los comentaris explicativos de cada función se quedan en el .cpp y ésta será la fuente de las clases para doxygen. Así se queda todo lo bueno de las 2 cosas.
Un único problema: Molesta una cabecera con la descripción encima de cada método en los .cpp?


Ejemplo:

Explicación de los métodos en el indice de clases


Captura de la copia de la cabecera que doxygen guarda
[/URL]

Snipet del fichero de código fuente


Mi pregunta es si prefieres la explicación detallada también en la cabecera, y el .cpp limpio para programar en el.

Espero que se entienda, y lamento el tamaño del post.

EDIT: Oye, pues lo dejaría así. Me gusta como hace una lista con los TODO y la función a la que pertenecen y como quedan las aclaraciones. Si te molestan, te hago un programa o un script que te los borre del código con el que trabajes. Pero con tiempecillo eh! (Aclaro, lo hago yo si es el caso porque sería culpa mía, obviamente no se trata de presumir ni hay nada de que hacerlo. Aclaro pa aquellos que lo lean de pasada )

Wow, ¡excelente!

Yn$an€ escribió:La doc está en html por defecto. Se podría subir a googlecode?

Perfecto. Si te sabes manejar con SVN, te doy permisos de escritura y añades la documentación en un directorio doc por ejemplo.

Yn$an€ escribió:Estoy haciendo que guarde copias de los archivos .h, que quedarán con los comentarios de línea simple.
Los comentaris explicativos de cada función se quedan en el .cpp y ésta será la fuente de las clases para doxygen. Así se queda todo lo bueno de las 2 cosas.
Un único problema: Molesta una cabecera con la descripción encima de cada método en los .cpp?

No tengo problema en que los ficheros se queden con los comentarios, de hecho lo prefiero Tampoco hay problema con quedarnos con estos comentarios sustituyendo los antiguos. Tampoco molesta la cabecera, más bien al contrario

Yn$an€ escribió:Espero que se entienda, y lamento el tamaño del post.

Perfecto, y no hay que lamentar los tamaños de los posts.

Con un poco de tiempo para aprender y terminar de documentar todo, por mi vale.

Perfecto, pues cuando quieras me mandas tu correo y te añado.

Saludos