juanjonavarro.com

secciones

Mi idea sobre Javadoc

Como dije en mi anterior post sobre la herramienta Javadoc, había tenido una idea para un proyecto que me parecía interesante y había encontrado que alguien ya lo había hecho antes.

Se trata de aprovechar la estructura de doclet de Javadoc y hacer que la documentación se introduzca en una base de datos (separada en tablas para clases, métodos, etc.) en lugar de generar un html estático. Después se puede hacer una aplicación web que permita interrogar esa bbdd. Una ventaja de este sistema es que permite realizar referencias cruzadas entre distintas API. Te habrá pasado alguna vez que consultando el javadoc de, por ejemplo, el api de servlets, habrás encontrado un método que devuelve un Iterator. En otro lugar de tu disco duro se encuentra el javadoc del J2SE que incluye la interface Iterator, sin embargo no puedes pulsar sobre el Iterator para que te lleve a la documentación de este interface ya que se trata de dos javadocs distintos. Con una herramienta como la que propongo esta referencia cruzada se podría realizar en tiempo de consulta. Otra ventaja de esta herramienta sería el sistema de búsqueda que puede llegar a ser muy potente y muy específico (bucar, por ejemplo, solo aquellos métodos no deprecated, públicos y que devuelvan un String).

La buena noticia es que la herramienta ya existe y es de código abierto. La puedes ver en funcionamiento en www.dbdoc.org y el código fuente de la herramienta lo puedes encontrar en el proyecto ashkelon de Souceforge.

En la web donde lo tienen en funcionamiento se puede encontrar la referencia de varios apis populares siendo una buena referencia online. Curiosamente no tienen disponible el api del J2SE ya que es necesario un permiso explicito de sun para ponerlo en un sitio público en internet. Por otro lado si bajas la herramienta y la instalas en tu intranet o en local en tu máquina, puedes poner cualquier api incluyendo el J2SE y la documentación de tus propios proyectos.

19 junio 2003 —
4 Comentarios
lasterra
lasterra
21 julio 2003, 13:44 — #1
bueno.. no se si será de ayuda, pero existe una herramienta que se llama java2html (www.java2html.com) que pasa de java a html. Esta herramienta pone un enlace a los javadoc de aquellas clases que estan incluidas en tu codigo, por ejemplo, pondria un enlace en Iterator a los javadoc de j2SE.

No se si te sirve de ayuda...pero de lo de meter una base de datos para ver los javaDocs me parece desiaoooo ;-)
Juanjo
21 julio 2003, 14:32 — #2
Bueno, en realidad no hace lo mismo. Esa herramienta que tu dices lo que hace es una versión html de los fuentes que les diga (con un enlace a javadoc, es cierto) pero la herramienta que yo digo lo que hace es publicar los javadoc en otro formato.

Si lo piensas lo de meter una base de datos para ver la documentación no está tan mal. Con esto tienes muchas opciones que un javadoc estático en html no te da, por ejemplo la estupenda busqueda avanzada que te permite afinar "mucho, mucho" (por ejemplo, clases de tipo abstract que implementen tal interface). Lo puedes ver en funcionamiento en http://www.dbdoc.org .

Un saludo.
lasterra
lasterra
21 julio 2003, 20:53 — #3
Esta claro.. al estar todo en base de datos da mucha mas funcionalidad.
Lo que queria decir es que bastaria con una funcionalidad similar a la de java2html para los javadoc, de manera que se puedan enlazar unos con otros.
En cualquiercaso, mirare mas afondo la herramienta. Si esa herramienta consigue que muchos programadores utilicen mas los javaDoc...la deberia de montar SUN¡¡

un saludo.
Juanjo
21 julio 2003, 21:03 — #4
De hecho SUN resaltó este proyecto como se puede ver en:

http://java.sun.com/features/2002/07/dbdoc.html

Un saludo.

Comentarios cerrados para este artículo