¿Existen algunas alternativas buenas y modernas a Javadoc? [cerrado]

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

Hay algunos recursos en la web que ofrecen Javadoc rediseñado. 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 con la búsqueda rápida de Firefox.

Pregunta práctica:
¿Existen aplicaciones independientes (de escritorio) que puedan explorar el Javadoc existente de una manera más utilizable que un navegador?
Estoy pensando en algo como el navegador de documentación de Mono.

Pregunta teórica:
¿Alguien sabe, si hay planes para hacer evolucionar Javadoc, de alguna manera estandarizada?
EDITAR: Un enlace útil a la wiki de Sun sobre este tema .

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

El nuevo doclet también realiza algunos cambios de estilo en el texto, pero el HTML generado no cambia en esta etapa.

Eso va de alguna manera a abordar los problemas de comentarios de HTML en Java, que es probablemente el mayor problema de usabilidad con Javadoc actual.

No creo que los conceptos de Javadoc estén desactualizados. Por lo que puedo ver, estos conceptos están arraigados 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 ( programación literaria ).

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

Además de eso, la presentación de la documentación se puede personalizar según sus necesidades especiales utilizando un sistema de complemento compatible con la herramienta JavaDoc. Puede proporcionar un complemento (como lo hacemos nosotros) que se publique directamente en una base de datos a la que se pueda acceder directamente a través de la web. Al utilizar colaboraciones, cualquier persona puede proporcionar comentarios o aclaraciones adicionales a la documentación que podrían encontrar su camino de regreso a la fuente original.

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

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

Estamos proponiendo mejoras en 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, se renovará la interfaz de usuario de la salida de javadoc. Las capturas de pantalla del nuevo diseño se cargan en la wiki del proyecto. El marcado de salida de javadoc se modificará para que sea compatible con HTML y WCAG 2.0 válido.

Así que definitivamente todavía hay trabajo allí, aunque sea algo tarde. Sin embargo, en mi opinión, uno de los mayores inconvenientes de Javadoc es su estrecha relación con HTML. Muchas clases tienen Javadoc, que incluye HTML literal y también se basa en HTML. Desafortunadamente, creo que esto no cambiará en ningún momento. Aún así, esto significa que los desarrolladores son libres de incluir lo que quieran en HTML allí, que también podría ser inválido, no estar bien formado, etc. Así que adaptar la salida de la herramienta javadoc es solo una parte de esto, la otra ganó ' 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. Normalmente uso la vista Javadoc en Eclipse. También tiene inconvenientes (lento y realmente no puedes buscar) pero es Good Enough ™ para la mayoría de las cosas.

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

Para la búsqueda: use el marco de búsqueda de Javadoc , hace que usar Javadoc de todo tipo sea mucho más fácil. Está disponible como un Usercript para Firefox y como una extensión de Google Chrome .

Para responder a su pregunta práctica, busqué en Google y les pregunté a mis amigos y se me ocurrieron estos. Forrestdoc, doclet y doxygen.

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

Es posible que desee expresarlo de una manera menos agresiva y autoritaria. A la mayoría de la gente no le importa cómo se ve un recurso técnico, y "¡No es suficiente Web 2.0!" suena como un insípido marketroidspeak.

¿Y qué consideraría exactamente "más utilizable"? 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 produzca el tipo de documento API que deseas?

Por qué nadie más ha hecho eso hasta ahora (que aparentemente es el caso) es una incógnita; tal vez nadie más lo sienta tan firmemente como tú.

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.

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

Por ejemplo, MarkDown, como se usa aquí, sería excelente, legible por humanos en la fuente, con un formato externo agradable a la fuente.

Con el JavaDoc actual, imagino que muchas personas usan comentarios de JavaDoc, pero en realidad no documentan en la medida en que podrían. Estoy seguro de que todo el mundo ha examinado el JavaDoc en línea de una API que no ha sido documentado o apenas está documentado y, por lo tanto, es mucho más difícil de usar de lo que debería ser.

Esto no ayuda con los reformateadores de código (por ejemplo, dentro de Eclipse, o tal vez en la confirmación de la fuente) que destruyen totalmente cualquier estructura legible que haya puesto dentro de un comentario de JavaDoc (por ejemplo, una lista de elementos) en una gran cantidad de texto, a menos que use literalmente dos retornos de carro donde desee usar uno).

¿Alguien sabe, si hay planes para desarrollar Javadoc, de alguna manera estandarizada?

El JSR correspondiente (JSR 260), que especifica mejoras en Javadoc, ha sido eliminado de JDK 7 (por ahora). Una descripción general de lo que se planeó (de este sitio ):

Actualice Javadoc para proporcionar un conjunto más rico de etiquetas para permitir una presentación más estructurada de la documentación de Javadoc. Este JSR cubre: categorización de métodos y campos, índice semántico de clases y paquetes, distinción de métodos estáticos, de fábrica, obsoletos de métodos ordinarios, distinción de accesos de propiedad, combinación y división de información en vistas, incrustación de ejemplos y casos de uso comunes, y más.

El panorama general para JDK 7 es bastante sombrío .

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 (usando XSLT 2.0 del lado del cliente en JS) para nuestro producto con JavaDoc completamente integrado. Para esto, se usó un doclet personalizado para producir datos JavaDoc en XML, este grupo de etiquetas usado para garantizar que incluso el marcado HTML dentro de los comentarios del código estuviera bien formado.

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

Aquí hay un enlace a un punto de entrada de muestra en la documentación bastante amplia: muestra de visor de JavaDoc

Aquí también hay una imagen:

Un visor javadoc inteligente con capacidad de conexión:

Muchas veces me enfrento al problema de navegar por JavaDoc. Estaba buscando algo como la opción de búsqueda de documentos de Adnroid. Por fin consigo algo así. Si usa Firefox, la solución está aquí.

1. Instale el complemento GreaseMonkey, su página web de personalización de la forma que vemos. (Necesitamos personalizar cualquier página de documentación de Java, para poder buscar el nombre de la clase) https://addons.mozilla.org/en-US/firefox/addon/greasemonkey/

2. Para que greasemonkey funcione, necesitamos algún script de usuario para personalizarlo. Greasemonkey puede descargarlo automáticamente. Instale el script de usuario desde el marco de búsqueda JavaDoc o la búsqueda incremental JavaDoc .

Esto funciona muy bien para mí.