Javadoc, ¿para Qué?

[_XUTI_H_]

 Bueno, cuando estudie Java en la universidad nos explicaron todas las ventajas que tenia poder documentar tus clases con JavaDoc y comprobe la facilidad con la que un programador podia acceder a información sobre las librerias, clases y código "ajeno" que utilizaba en sus programas.

Pero ahora estoy documentando un proyecto por mi cuenta y me surgen dudas de la limitación que puede tener su utilización. Partimos de que tu documentas unas clases para que el que no tenga el código fuente (o no quiera mirarselo a pelo) pueda comprender que prestaciones le ofrecen unas clases y métodos ya implementadas, por tanto no se documentan las clases o mètodos privados.

Pero, ¿y si quiero documentar mi trabajo en formato web para que alguien vea que hace cada método aunque sea privado?. Quiero decir, si hago un juego, puedo querer dejar constancia de mi trabajo fuera del código. En principio no solo para que se utilicen mis clases por otros, sino para explicar como funcionan también internamente (por lo que necesitamos de la documentación de mètodos privados).

Seguramente solo se reduce a poner algun parámetro a JavaDoc para que también contemple la docu de los mètodos y clases privadas. Pero lo importante es si  pensais que es una buena forma de hacerlo, o para esto considerais mejor poner comentarios "estandar" (no javadoc) y a la marxa. ¿Alguna otra sugerencia para documentar bien el funcionamiento interno?

Bueno, espero que os parezca un tema interesante de comentar.
Aunque sea por interés particular  :rolleyes:
Saludos y gracias

Edit: Por cierto, para mostrar tanto publicos, protecteds, como privados, el parámetro de JavaDoc es -private. Si ya lo sé, sencillo, ¿pero sigue siendo una buena opción?.

[sés]

 Al generar la documentación puedes decir qué partes quieres que se muestren. Creo que por defecto no genera documentación de métodos privados.

Yo suelo documentar TODO, tanto público como privado. Luego genero en HTML lo que necesite.
Los comentarios clásicos (no javadoc) los dejo para explicaciones del funcionamiento del código en si.

[zupervaca]

 igual que ses, cuando haces proyectos para empresas es importante documentarlo todo si quieres que vuelvan a contar contigo para otros proyectos ;)

[_XUTI_H_]

 

Yo suelo documentar TODO, tanto público como privado. Luego genero en HTML lo que necesite.
Los comentarios clásicos (no javadoc) los dejo para explicaciones del funcionamiento del código en si.

Vale, entonces como yo lo hago ... gracias sés, era el apoyo que necesitaba :)

Pero para móviles el tema de que con nombres grandes de mètodos y muchos comentarios en el fuente, el tamaño del class se dispara es cierto,¿no?
¿El tema la ofuscación o comoc*ñ*sediga al crear el paquete soluciona este problema, o no del todo?
(q por cierto no se muy bien que es la tal  obfuscation)

Me mola que quede todo bien documentado, pero lidiar con el tamaño del jar viene siendo una ardua tarea XDDDD
¿Más opiniones? Gratxias

¡¡¿sés y zuper de acuerdo?!! No me lo creo, jejeje XDDDD

[CoLSoN2]

Pero para móviles el tema de que con nombres grandes de mètodos y muchos comentarios en el fuente, el tamaño del class se dispara es cierto,¿no?
¿El tema la ofuscación o comoc*ñ*sediga al crear el paquete soluciona este problema, o no del todo?
(q por cierto no se muy bien que es la tal  obfuscation)'

Dudo que los comentarios afecten porque un .class es bytecode, código ejecutable, y dudo que se incluyan los comentarios. Lo de los nombres de métodos grandes, ya no se hasta qué punto afecta..

[sés]

 

Dudo que los comentarios afecten porque un .class es bytecode, código ejecutable, y dudo que se incluyan los comentarios.

X'DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD


(uoh) ¡Bienvenido al maravilloso mundo de Java!

[sés]

 Bueno... que no cunda el pánico X'D

Esto solo sucede si incluyes información de depuración y con comentarios MUY grandes. Pero sucede X'D

Lo de los nombres largos si que afecta, pero al ofuscar no debería notarse. Precisamente una de las cosas que hace un ofuscador es cambiar todos los nombres de las variables y métodos para que sea ilegible. Así que te da igual los que tú pongas.

[zupervaca]

 me ha dado cuenta que el ofuscador del netbeans poniendolo al maximo la clase midlet no te la ofusca o por lo menos parte de ella, no se si me esta coincidiendo en el proyecto que tengo o si siempre es asi, las demas clases te las renombra por letras y las funciones tambien, si esto es asi es aconsejable que la clase midlet sea la minima expresion O_O