Existe-t-il des alternatives bonnes et modernes à Javadoc?

Let’s face it: Vous n’avez pas besoin d’être un concepteur pour voir que Javadoc par défaut a l’ air moche .

Il existe des ressources sur le Web qui offrent un Javadoc redessiné. Mais le comportement par défaut représente le produit et devrait être raisonnablement beau.

Un autre problème est le fait que l’utilisation de Javadoc n’est pas à jour par rapport à d’autres ressources similaires.

Les projets particulièrement complexes sont difficiles à naviguer en utilisant la recherche rapide de Firefox.

Question pratique:
Existe-t-il des applications autonomes (de bureau) capables de parcourir le Javadoc existant d’une manière plus utilisable qu’un navigateur?
Je pense à quelque chose comme le navigateur de documentation de Mono.

Question théorique:
Est-ce que quelqu’un sait, s’il existe des plans pour faire évoluer Javadoc, d’une manière quelque peu standardisée?
EDIT: Un lien utile vers le wiki de Sun sur ce sujet .

J’ai créé un doclet Markdown (java) qui prendra les commentaires source dans le texte mis en forme Markdown et créera les mêmes fichiers Javadocs HTML.

Le nouveau doclet fait également du restyling sur le texte, mais le code HTML généré n’est pas modifié à ce stade.

Cela permet de résoudre les problèmes de commentaires HTML-in-java, qui sont probablement le plus gros problème d’utilisation avec le Javadoc actuel.

Je ne pense pas que les concepts de Javadoc soient dépassés. Autant que je sache, ces concepts sont enracinés il y a des années dans un produit nommé doxygen, qui est toujours disponible pour d’autres langages (c.-à-d. Objective-C où il est très utilisé). Même avec ses prédécesseurs – jetez un coup d’œil à l’environnement de programmation utilisé par Donald Knuth pour créer TeX ( programmation alphabétisée ).

Néanmoins, il est intéressant d’avoir une source unique pour le code du programme et la documentation.

En outre, la présentation de la documentation peut être personnalisée en fonction de vos besoins spécifiques grâce à un système de plug-in pris en charge par l’outil JavaDoc. Vous pouvez fournir un plug-in (comme nous) qui publie directement dans une firebase database directement accessible via le Web. En utilisant des collaborations, tout le monde peut fournir des commentaires supplémentaires ou des clarifications à la documentation qui pourraient retourner dans la source d’origine.

Javadoc est le meilleur système de génération de documentation automatique de code source que j’ai jamais vu. Une grande partie de cela est que c’est si simple – je peux parcourir javadocs même avec mon téléphone portable de 5 ans si je le veux! Bien que JDK soit un peu difficile à parcourir, je ne serais pas prêt à réinventer entièrement la roue, car nous avons actuellement une solution RESTful, facile à utiliser, qui fonctionne à peu près partout.

J’ai récemment reçu un courrier que Sun travaille à la modernisation de la sortie HTML de Javadoc. De ce courrier:

Nous proposons des améliorations à javadoc / doclet pour JDK7. La page wiki du projet se trouve à l’ adresse http://wikis.sun.com/display/Javadoc/Home . Dans le cadre des améliorations proposées, l’interface utilisateur de la sortie javadoc sera réorganisée. Les nouvelles captures d’écran du design sont téléchargées sur le wiki du projet. Le balisage de sortie javadoc sera modifié pour être compatible HTML et WCAG 2.0.

Donc, il y a encore du travail, même si c’est un peu tard. Cependant, l’un des plus gros inconvénients de Javadoc est à mes yeux son couplage très étroit avec HTML. De nombreuses classes ont Javadoc qui inclut le HTML littéral et repose sur la sortie HTML. Malheureusement, cela ne changera pas, je pense. Cependant, cela signifie que les développeurs sont libres d’inclure tout ce qu’ils veulent dans le HTML, ce qui pourrait aussi bien être invalide, non bien formé, etc. Donc, l’adaptation de la sortie de l’outil javadoc n’est qu’une partie de cela, l’autre a gagné. t et ne peut pas changer et rest donc.

En ce qui concerne la documentation de navigation, je trouve également la documentation HTML un peu lourde. J’utilise généralement la vue Javadoc dans Eclipse. Il a aussi des inconvénients (lent et vous ne pouvez pas vraiment chercher) mais c’est Good Enough ™ pour la plupart des choses.

Pour répondre à votre question pratique, j’ai googlé et demandé à des amis et est venu avec ceux-ci. Forrestdoc, doclet et doxygen.

La deuxième question, je dirais que oui, ce n’est pas très “Web-oh-twoeye” mais au moins, votre garantie de travailler dans un environnement hors ligne, et son assez petit pour être livré avec votre API. Je dispense l’utilisation des frameworks, mais cela fonctionne plutôt bien pour le javadoc. Je n’ai vu aucun plan pour le changer. Eclipse prend en charge javadoc en ce qui concerne la lecture, l’interprétation et la génération.

Personnellement, je trouve toujours Javadoc très utile. Surtout depuis qu’il est standardisé. Je ne connais aucun style de documentation majeur que je trouve plus facile à naviguer (cela pourrait très bien être subjectif, mais je trouve personnellement que MSDN est horrible à utiliser, par exemple).

Pour la recherche: utilisez le cadre de recherche Javadoc , cela simplifie grandement l’utilisation de Javadoc. Il est disponible sous forme de script utilisateur pour Firefox et d’ extension Google Chrome .

Vous voudrez peut-être formuler cela d’une manière moins agressive et dominasortingce. La plupart des gens ne se soucient pas à quoi ressemble une ressource technique, et “Ce n’est pas assez Web 2.0!” sonne comme vapotant marketroidspeak.

Et que diriez-vous exactement “plus utilisable”? Personnellement, je voudrais certainement une recherche en texte intégral et un meilleur navigateur, et AJAX pourrait probablement les aider.

Eh bien, la bonne chose à propos de JavaDoc est que c’est l’opposé de obsolète – il est arbitrairement extensible. Pourquoi ne pas aller de l’avant et écrire un doclet qui produit le type de document API que vous voulez?

Pourquoi personne d’autre n’a fait cela jusqu’ici (ce qui est apparemment le cas), c’est ce que l’on peut supposer – peut-être que personne d’autre ne le pense aussi fortement que vous.

Il y a un doclet DocBook. DocBook est un type de document plus riche que le (X) HTML et convient mieux à la description de contenu technique. Depuis la source DocBook, vous pouvez générer toutes sortes de formats de sortie différents.

Personnellement, je voudrais un standard plus lisible de la “documentation de commentaire” que le HTML (et donc le tag-wieldy) JavaDoc.

Par exemple, MarkDown, tel qu’il est utilisé ici, serait excellent, lisible par l’homme dans la source, bien formaté à l’extérieur de la source.

Avec le JavaDoc actuel, j’imagine que beaucoup de gens utilisent les commentaires JavaDoc, mais ne documentent pas réellement ce qu’ils pourraient. Je suis sûr que tout le monde a parcouru le JavaDoc en ligne d’une API non documenté ou peu documenté, et donc beaucoup plus difficile à utiliser que prévu.

Cela n’est pas aidé par les reformateurs de code (par exemple, dans Eclipse, ou peut-être lors de la validation de la source) qui détruisent totalement toute structure lisible dans un commentaire JavaDoc (par exemple une liste d’éléments) sauf si vous utilisez littéralement deux retours chariot lorsque vous souhaitez en utiliser un).

Est-ce que quelqu’un sait, s’il existe des plans pour faire évoluer Javadoc, d’une manière quelque peu standardisée?

Le JSR correspondant (JSR 260), qui spécifie les améliorations apscopes à Javadoc, a été retiré du JDK 7 (pour le moment). Un aperçu de ce qui était prévu (à partir de ce site ):

Mettez Javadoc à niveau pour fournir un ensemble de balises plus riche afin de permettre une présentation plus structurée de la documentation Javadoc. Ce JSR couvre: la catégorisation des méthodes et des champs, l’index sémantique des classes et des packages, la distinction entre les méthodes statiques, usine, obsolètes des méthodes ordinaires, la distinction des accesseurs de propriétés, la combinaison et la séparation des informations en vues, et plus.

Les outlook générales pour JDK 7 sont plutôt sombres .

JavaDoc est lui-même extrêmement flexible car vous pouvez remplacer le doclet standard par un doclet personnalisé pour fournir quelque chose qui réponde aux besoins spécifiques de vos projets.

Sur le projet sur lequel j’ai travaillé, nous avons créé un système de documentation basé sur HTML / XML (utilisant XSLT 2.0 côté client sur JS) pour notre produit avec JavaDoc entièrement intégré. Pour cela, un doclet personnalisé a été utilisé pour produire des données JavaDoc en XML, cette balise utilisée pour garantir que même le balisage HTML dans les commentaires de code était bien formé.

Grâce à cela, nous avons pu offrir une expérience utilisateur interactive à l’aide d’une application à une seule page (similaire à un outil de bureau), mais à partir du navigateur, sans aucune infrastructure / code côté serveur. Le visualiseur comprenait des fonctionnalités standard telles que la recherche, la navigation dans les arbres, etc.

Voici un lien vers un exemple de point d’entrée dans la documentation plutôt vaste: exemple de visualiseur JavaDoc

Voici une image aussi: entrer la description de l'image ici

Une visionneuse intelligente de javadoc accessible en mer:

Pour de nombreuses fois, je suis confronté au problème de la navigation sur JavaDoc. Je cherchais quelque chose comme l’option de recherche doc Adnroid. Enfin, j’ai quelque chose comme ça. Si vous utilisez Firefox, la solution est ici.

  1. Installez le plug-in GreaseMonkey, sa page Web de personnalisation comme nous voyons. (Nous avons besoin de personnaliser n’importe quelle page de doc java, donc nous pouvons rechercher le nom de la classe) https://addons.mozilla.org/en-US/firefox/addon/greasemonkey/

  2. Pour que greasemonkey fonctionne, nous avons besoin d’un script utilisateur pour la personnalisation. Cela peut être téléchargé par greasemonkey automatiquement. Installez le script utilisateur à partir du cadre de recherche JavaDoc ou de la recherche incrémentielle JavaDoc .

Cela fonctionne très bien pour moi.