how - ¿Hay algunas buenas y modernas alternativas a Javadoc?
javadoc java 8 example (12)
Reconozcámoslo: no necesitas ser diseñador para ver que el Javadoc predeterminado 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.
Pregunta práctica:
¿Hay alguna aplicación independiente (de escritorio) que pueda explorar el Javadoc existente de una manera más útil que la que tendría un navegador?
Estoy pensando en algo como el navegador de documentación de Mono.
Pregunta teórica
¿Alguien sabe si hay algún plan para evolucionar Javadoc, de alguna manera estandarizada?
EDITAR: Un enlace útil al wiki de Sun sobre este tema .
¿Alguien sabe si hay algún plan para evolucionar Javadoc, de alguna manera estandarizada?
El JSR correspondiente (JSR 260), que especifica mejoras a Javadoc, ha sido votado fuera de JDK 7 (por ahora). Una visión general de lo que se planificó (desde este sitio ):
Actualice Javadoc para proporcionar un conjunto de etiquetas más completo para permitir una presentación más estructurada de la documentación de 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 bastante sombrío .
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é exactamente considerarías "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 ahora (que aparentemente es el caso) es una incógnita, quizás nadie más se sienta tan seguro como usted.
Hace poco recibí un correo reenviado que Sun está trabajando en la modernización de la salida HTML de Javadoc. De 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, la interfaz de usuario de la salida de javadoc se renovará. Las nuevas capturas de pantalla de diseño se cargan en la wiki del proyecto. El marcado de salida de javadoc se modificará para que sea válido en HTML y compatible con WCAG 2.0.
Por lo tanto, definitivamente todavía hay trabajo en marcha allí, aunque sea algo 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, la documentación HTML me resulta un tanto 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.
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.
He creado un Doclet Markdown (java) que tomará los comentarios fuente en texto con formato Markdown y creará los mismos Javadocs HTML.
El nuevo doclet también hace un poco de restyling en el texto, pero el HTML generado no se cambia en esta etapa.
Eso va de alguna manera a abordar los problemas de HTML en Java-comment, que probablemente sea el mayor problema de usabilidad con el Javadoc actual.
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 XSLT 2.0 en JS para el cliente) 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 incluía funciones estándar como búsqueda, navegación en árbol, etc.
Aquí hay un enlace a un punto de entrada de muestra en la vasta documentación: muestra de visor JavaDoc
Aquí hay una imagen también:
Javadoc es el mejor sistema de generación de auto-documentación de código fuente que he visto en mi vida. 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.
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 idiomas (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 de Literate ).
Sin embargo, es una idea intrigante tener una única fuente de código de programa y 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 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.
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 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.
Personalmente, me gustaría obtener un estándar de "documentación de comentarios" más legible que el HTML (y por lo tanto, con una etiqueta) 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 los comentarios de 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 reformadores 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 una gran cantidad de texto, a menos que literalmente use dos retornos de carro donde desee usar uno).
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 marco de búsqueda de Javadoc , hace que el uso de Javadoc de todo tipo sea mucho más fácil. Está disponible como un Userscript para Firefox y como una extensión de Google Chrome .
Un visor de javadoc inteligente que puede ser encapsulado:
Muchas veces, me enfrento al problema de explorar 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í.
Instala el complemento GreaseMonkey, es una especie de página web personalizable de la manera que vemos. (Necesitamos personalizar cualquier página de doc de Java, para que podamos buscar el nombre de la clase) https://addons.mozilla.org/en-US/firefox/addon/greasemonkey/
Para que greasemonkey funcione, necesitamos algunas secuencias de comandos de usuario para la personalización. Esto puede ser descargado por greasemonkey automáticamente. Instale el UserScript desde el marco de búsqueda JavaDoc o la búsqueda incremental JavaDoc .
Esto funciona genial para mí