Y a-t-il des alternatives bons et modernes pour Javadoc ?

Question

Avouons-le: Vous n'avez pas besoin d'être un designer de voir que par défaut Javadoc semble laid.

Il y a quelques ressources sur le web qui offre style Javadoc. Mais le comportement par défaut représente le produit et devrait être raisonnablement agréable à regarder.

Un autre problème est le fait que la facilité d'utilisation de Javadoc n'est pas à jour par rapport à d'autres ressources similaires.

En particulier pour les projets volumineux, il est difficile de naviguer à l'aide de Firefox avec la recherche rapide.

Question pratique:
Y a-autonome (bureau) applications qui sont en mesure de naviguer existant Javadoc dans un plus utilisable qu'un navigateur?
Je suis en train de réfléchir à quelque chose comme Mono documentation du navigateur.

Question théorique:
Personne ne sait, si il y a certains plans d'évoluer Javadoc, dans un d'une certaine manière standardisée?
EDIT: UN lien utile pour le Soleil " wiki sur ce sujet.

Answer 1

J’ai créé une démarque (java) Doclet qui aura commentaires source Markdown au format texte et créer les Javadocs même de HTML.

Le nouveau doclet fait aussi quelques restylage sur le texte, mais le code HTML généré n’est pas modifié à ce stade.

Cela va de certaine façon pour résoudre les problèmes de HTML-en-java-commentant ce qui est probablement le plus gros problème d’utilisabilité avec Javadoc actuel.

Answer 2

Je ne pense pas que les concepts de la Javadoc sont obsolètes. Aussi loin que je peux voir, ces concepts sont enracinées il y a des années dans un produit nommé doxygen, qui est toujours disponible pour les autres langues (c'est à dire Objective-C, où il est très utilisé). Même si ce dernier a ses prédécesseurs - avoir un regard sur l'environnement de programmation utilisé par Donald Knuth pour créer TeX (Lettré de programmation).

Néanmoins, c'est une idée intéressante d'avoir une seule source pour le code du programme et de la documentation.

En plus de cela, la présentation de la documentation peut être personnalisé en fonction de vos besoins particuliers à l'aide d'un plug-in système pris en charge par l'outil JavaDoc. Vous pourriez fournir un plug-in (comme nous) qui publie directement dans une base de données qui est directement accessible par le web. À l'aide de collaborations quelqu'un peut fournir des commentaires supplémentaires ou des clarifications quant à la documentation qui pourraient trouver leur chemin de retour dans la source d'origine.

Answer 3

Javadoc est la meilleure source code auto-génération système de documentation que j’ai jamais vu. Grande partie de cela est que c’est si simple - je peux naviguer javadocs même avec mon téléphone portable vieux de 5 an si je veux ! Je conviens qu’un peu d’une remontée du visage pourrait être dans l’ordre et surtout de JDK est une douleur pour parcourir, je n’oserait pas réinventer la roue entièrement car ce que nous avons actuellement est un RESTful, solution facile à utiliser aux fins qui fonctionne à peu près partout.

Answer 4

J'ai reçu récemment un courrier que le Soleil est de travail sur la modernisation de la Javadoc de la sortie HTML. De dit-mail:

Nous proposons des améliorations à javadoc/doclet pour JDK7. L' projet page wiki est situé à http://wikis.sun.com/display/Javadoc/Home. En tant que partie du projet de améliorations de l'INTERFACE utilisateur de la javadoc de sortie sera remanié. La nouvelle la conception des captures d'écran sont téléchargées sur le projet wiki. La javadoc de sortie le balisage sera modifié pour être valide HTML et les WCAG 2.0.

Il n'y a donc encore du travail à faire là-bas, même si un peu en retard. Cependant, à mes yeux l'un des plus grands inconvénients de la Javadoc est son très proche de couplage avec le HTML. De nombreuses classes ont Javadoc qui comprend littérale HTML et s'appuie sur la sortie HTML, trop. Malheureux, mais cela ne va pas changer à tout moment, je pense. Encore, cela signifie que les développeurs sont libres d'inclure tout ce qu'ils veulent en HTML qui pourrait aussi bien être invalide, non bien formé, etc. Afin d'adapter la sortie à partir de la javadoc de l'outil n'est qu'une partie de cela, les autres ne seront pas et ne peut pas changer et reste ainsi.

Comme pour naviguer dans la documentation je trouve aussi que la documentation HTML un peu difficile. J'ai l'habitude d'utiliser la Javadoc vue dans Eclipse. Il a des inconvénients (lent et vous ne pouvez pas vraiment de la recherche) mais elle est Assez Bonne™ pour la plupart des choses.

Answer 5

Pour répondre à votre Question Pratique, j'ai googlé et demandé à des amis et est venu avec ces. 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 expédier avec votre API. je dispise l'utilisation des images, mais il fonctionne plutôt bien pour javadoc. Je n'ai pas vu les plans de la changer. Eclipse a un certain appui pour la javadoc autant que la lecture, l'interprétation et la génération de il va.