¿Hay algunas alternativas buenas y modernas para Javadoc?

Question

Seamos realistas: no es necesario ser un diseñador para ver que predeterminado Javadoc se ve feo.

Hay algunos recursos en la web que ofrecen rediseñado Javadoc. Pero el comportamiento predeterminado representa el producto y debe ser razonablemente atractivo.

Otro problema es el hecho de que la usabilidad de Javadoc no está actualizada en comparación con otros recursos similares.

Los proyectos especialmente grandes son difíciles de navegar usando la búsqueda rápida de Firefox.

cuestión práctica:
¿Hay algunas aplicaciones independientes (de escritorio) que son capaces de navegar Javadoc existentes de una manera más útil que un navegador lo haría?
Estoy pensando en algo así como el navegador de documentación de Mono.

cuestión teórica:
¿Alguien sabe, si hay algunos planes para evolucionar Javadoc, de manera alguna manera estandarizada ?
EDITAR:A useful link to Sun' wiki on this topic.

Answer 1

Hay un doclet de DocBook. DocBook es un tipo de documento más rico que (X) HTML y es mejor para describir contenido técnico. Desde la fuente DocBook puede generar todo tipo de formatos de salida diferentes.

Answer 2

No creo que los conceptos de Javadoc estén desactualizados. Hasta donde puedo ver, estos conceptos están enraizados hace años en un producto llamado doxygen, que todavía está disponible para otros lenguajes (es decir, Objective-C, donde se usa mucho). Incluso esto tiene sus predecesores: eche un vistazo al entorno de programación utilizado por Donald Knuth para crear TeX (Literate programming).

Sin embargo, es una idea intrigante tener una sola fuente para el código del programa y la documentación.

Además de eso, la presentación de la documentación puede personalizarse para sus necesidades especiales utilizando un sistema de complemento compatible con la herramienta JavaDoc. Puede proporcionar un complemento (como nosotros) que se publica directamente en una base de datos a la que se puede acceder directamente a través de la web. Al usar colaboraciones, cualquiera puede proporcionar comentarios adicionales o aclaraciones a la documentación que pueda encontrar su camino de regreso a la fuente original.

Answer 3

Para responder a su pregunta práctica, busqué en Google y pregunté a amigos y se me ocurrió esto. Forrestdoc, doclet y doxygen.

La segunda pregunta, diría que sí, no es muy "web-oh-twoeye", pero al menos garantiza que trabajará en un entorno fuera de línea, y es lo suficientemente pequeña como para enviar junto con su API. disculpo el uso de marcos, pero luego funciona bastante bien para javadoc. No he visto ningún plan para cambiarlo. Eclipse tiene cierto soporte para javadoc en lo que respecta a la lectura, interpretación y generación.

Answer 4

Es posible que desee expresar eso de una manera menos agresiva y autoritaria. A la mayoría de las personas no les importa cómo se ve un recurso técnico, y "¡No es suficiente Web 2.0!" suena como marketroidspeak insulso.

¿Y qué es exactamente lo que consideraría "más útil"? Personalmente, definitivamente me gustaría una búsqueda de texto completo y un mejor navegador de uso, y AJAX probablemente podría ayudar con eso.

Bueno, lo bueno de JavaDoc es que es lo opuesto a obsoleto: es arbitrariamente extensible. ¿Por qué no sigues adelante y escribes un doclet que produce el tipo de documento API que quieres?

Por qué nadie más ha hecho eso hasta el momento (que aparentemente es el caso) nadie lo adivina, tal vez nadie más lo siente tan fuertemente como usted.

Answer 5

Personalmente, todavía encuentro que Javadoc es muy útil. Especialmente porque está estandarizado. No conozco ningún estilo importante de documentación que me resulte más fácil de navegar (que bien podría ser subjetivo, pero personalmente encuentro MSDN horrible de usar, por ejemplo).

Para la búsqueda: Utilice el Javadoc Search Frame, hace que usar Javadoc de todo tipo sea mucho más fácil. Está disponible como Userscript for Firefox y como Google Chrome Extension.

Answer 6

Javadoc es el mejor sistema de generación de auto-documentación de código fuente que he visto. Gran parte de eso es que es muy simple: ¡puedo navegar por javadocs incluso con mi teléfono celular de 5 años si quiero! Si bien estoy de acuerdo en que un poco de cirugía estética podría estar en orden y especialmente JDK es un dolor para examinar, no me atrevería a reinventar la rueda por completo porque lo que tenemos actualmente es una solución RESTful, fácil de usar para su propósito que funciona casi en cualquier lugar.

Answer 7

Recientemente recibí un correo reenviado que Sun está trabajando en la modernización de la salida HTML de Javadoc. Desde dicho correo:

Estamos proponiendo mejoras a javadoc/doclet para JDK7. La página wiki del proyecto se encuentra en http://wikis.sun.com/display/Javadoc/Home. Como parte de las mejoras propuestas en , se actualizará la interfaz de usuario de la salida de javadoc. Las nuevas capturas de pantalla del diseño se cargan en la wiki del proyecto. La marca de salida javadoc se modificará para que sea válida según HTML y WCAG 2.0.

Por lo tanto, definitivamente todavía hay trabajo pasando allí, aunque un poco tarde. Sin embargo, a mis ojos, uno de los mayores inconvenientes de Javadoc es su acoplamiento muy cercano con HTML. Muchas clases tienen Javadoc que incluye HTML literal y se basa en que la salida también es HTML. Desafortunado, pero esto no cambiará en cualquier momento, creo. Aún así, esto significa que los desarrolladores pueden incluir en HTML lo que deseen, que también podría ser inválido, no bien formado, etc. Por lo tanto, adaptar el resultado de la herramienta javadoc es solo una parte de esto, el otro no t y no puede cambiar y por lo tanto permanece.

En cuanto a la documentación de navegación, también encuentro la documentación HTML un poco difícil de manejar. Usualmente uso la vista de Javadoc en Eclipse. También tiene inconvenientes (es lento y no se puede buscar) pero es Good Enough ™ para la mayoría de las cosas.

Answer 8

Personalmente me gustaría tener un estándar de "documentación de comentarios" más legible que el HTML (y por lo tanto, con una gran cantidad de etiquetas) de JavaDoc.

Por ejemplo, MarkDown, como se usa aquí, sería excelente, legible para el ser humano en la fuente, con un buen formato externo a la fuente.

Con el JavaDoc actual, imagino que muchas personas usan comentarios JavaDoc, pero en realidad no documentan en la medida de lo posible.Estoy seguro de que todos han navegado por JavaDoc en línea de una API que no ha sido documentado o apenas documentado, y por lo tanto es mucho más difícil de usar de lo que debería ser. Esto no es ayudado por reformateos de código (por ejemplo, dentro de Eclipse o tal vez en la confirmación de origen) que destruyen totalmente cualquier estructura legible que haya puesto dentro de un comentario JavaDoc (por ejemplo, una lista de elementos) en un gran blob de texto, a menos que literalmente use dos retornos de carro donde desee usar uno).

Answer 9

¿Alguien sabe, si hay algunos planes para evolucionar Javadoc, de una manera estandarizada de alguna manera?

El JSR correspondiente (JSR 260), que especifica las mejoras de Javadoc, ha sido votado fuera de JDK 7 (por ahora). Una visión general de lo que estaba previsto (de this site): Javadoc

de actualización para proporcionar un conjunto más rico de etiquetas para permitir la presentación más estructurada de la documentación Javadoc. Esta JSR abarca: categorización de métodos y campos, índice semántico de clases y paquetes, distinción de métodos estáticos, fábrica, desaprobados de métodos ordinarios, distinción de acceso a propiedades, combinación y división de información en vistas, incorporación de ejemplos y casos de uso comunes, y más.

El panorama general para JDK 7 es pretty grim.

Answer 10

He creado un Markdown (java) Doclet que tomará los comentarios fuente en texto con formato Markdown y creará los mismos Javadocs HTML.

El nuevo doclet también hace un restyling en el texto, pero el HTML generado no se cambia en esta etapa.

Eso soluciona los problemas de HTML-in-java-commenting que probablemente sea el mayor problema de usabilidad con el Javadoc actual.

Answer 11

Un visor javadoc seachable inteligente:

Para muchas veces, se enfrentan al problema de la navegación JavaDoc. Estaba buscando algo así como la opción de búsqueda de documentos Adnroid. Por fin consigo algo así. Si usa Firefox, la solución está aquí.

1. Instalar el complemento Greasemonkey, su página Web un poco la personalización de la forma en que vemos. (Necesitamos personalizar cualquier página de documento de Java, por lo que podemos buscar en nombre de la clase) https://addons.mozilla.org/en-US/firefox/addon/greasemonkey/

2. Para Greasemonkey para trabajar, necesitamos una secuencia de comandos de usuario para la personalización. Esto puede ser descargado por greasemonkey automáticamente. Instale el userscript desde JavaDoc search frame o JavaDoc incremental search.

Esto funciona muy bien para mí.

Answer 12

JavaDoc es en sí mismo extremadamente flexible porque puede reemplazar el doclet estándar con un doclet personalizado para proporcionar algo que satisfaga las necesidades específicas de su proyecto.

En el proyecto en el que he estado trabajando, creamos un sistema de documentación basado en HTML/XML (utilizando el cliente XSLT 2.0 en JS) para nuestro producto con JavaDoc completamente integrado.Para esto, se utilizó un doclet personalizado para producir datos JavaDoc en XML, esto usó tagoup para asegurar que incluso el marcado HTML dentro de los comentarios del código estuviera bien formado.

Con esto, pudimos ofrecer una experiencia de usuario interactiva utilizando una aplicación de una sola página (similar a una herramienta de escritorio), pero todo desde el navegador, sin ningún código/infraestructura del lado del servidor. El visor incluye características estándar tales como búsqueda, el árbol de navegación, etc.

Aquí hay un enlace a un punto de entrada de la muestra en el lugar vasta documentación: JavaDoc viewer sample

Aquí está una imagen también: