Il y aurait des bons et des solutions de rechange modernes à Javadoc?
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 beau.
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-méthode normalisée?
EDIT: Un lien utile pour le Soleil " wiki sur ce sujet.
- Je serais heureux si javadoc permettrait de générer valide HTML 4.01 ou XHTML pages.
- Ce usabilitiy problèmes avez-vous?
- Pourquoi serait-on downvote cela? Je pense que c'est une question raisonnable: +1
- (X)HTML ne doit pas être le seul moyen de Javadoc. Le navigateur est très limité outil pour accéder à un (local) de la base de connaissances.
- La recherche de la documentation du JDK avec Firefox avec la recherche rapide n'est pas très utilisable 😉 -- @Daniel: Certaines personnes semblent le prendre personnel, quand quelqu'un déteste la Javadoc.
- Les gens seraient downvote ce parce que c'est formulé de façon arrogante et agressive.
- Personnellement, j'aime Javadoc. Il est clair, concis et précis. Le site MSDN de l'autre main...
- Veuillez faire votre vrai nom, je suis très envieux
- ok, je vais supprimer "obsolète" à partir de la question du titre -- @oxbow_lakes: c'est près de mon vrai nom 😉
- Je voudrais classer les "Web 1.0" comme un retronym - en.wikipedia.org/wiki/Retronym
- M - je vous remercie pour le beau terme "retronym", je l'aime!
- J'ai essayé de reformuler la question pour être moins argumentatif, parce que je crois que la question de la peine de discuter.
- Il est vrai. Javadoc est coincé dans les années 1990. Pas une réponse, mais j'ai demandé quelque chose de similaire d'un moment de retour: stackoverflow.com/questions/382114/javafx-and-javadoc
- Rouvert. Sympa 😉
- Il n'est pas et n'a pas été formulé de façon arrogante et agressive, tout simplement pas le politiquement correct et suffisant. L'écriture de code HTML en Java était une bonne idée, il y a 20 ans, mais maintenant il se sent tout simplement terrible, comparativement à markdown.
- Dommage que aucune de ces réponses a été accepté... hint hint
Vous devez vous connecter pour publier un commentaire.
J'ai créé un Markdown (java) Doclet qui prendra la source des commentaires en Markdown texte mis en forme et créer le même code HTML Javadoc.
La nouvelle doclet aussi fait un peu de relooking sur le texte, mais le code HTML généré n'est pas modifié à ce stade.
Qui va d'une certaine manière à l'adresse HTML-en-java commentant les questions qui est probablement la plus grande convivialité problème avec la Javadoc.
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.
Javadoc est la meilleure source de code à l'auto-documentation du système de production que j'ai jamais vu. Grande partie de cela est qu'il est tellement simple que je peux parcourir la documentation javadoc même avec mes 5 ans de téléphone cellulaire si je veux! Alors que je suis d'accord qu'un peu d'un lifting peut être dans l'ordre et surtout JDK est une douleur à parcourir, je n'ose pas réinventer la roue tout à fait parce que ce que nous avons actuellement est un Reposante, facile à utiliser la solution pour son but qui fonctionne à peu près n'importe où.
http://download.oracle.com/javase/6/docs/api/java/lang/String.html#String(byte[])
) ne sont pas valides car ils utilisent les parenthèses, les crochets et autres personnages qui ne sont pas permis. Cela les pousse à casser dans certains navigateurs.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:
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.
Que 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.
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.
Personnellement, je trouve toujours Javadoc pour être très utile. Surtout depuis qu'il est standardisé. Je ne sais pas du tout majeures de la documentation style que je trouve plus facile à naviguer (qui pourrait très bien être subjectif, mais je trouve personnellement MSDN horrible à utiliser, par exemple).
Pour la recherche: l'Utilisation de la Javadoc De Recherche D'Image, il rend l'utilisation de Javadoc de toutes sortes beaucoup plus facile. Il est disponible comme un Script pour Firefox et Google Chrome Extension.
Vous pourriez phrase qui est moins agressif et dominateur manière. La plupart des gens ne se soucient pas ce qu'est une ressource technique ressemble, et "Ce n'est pas Web 2.0 assez!" sonne comme insipide marketroidspeak.
Et exactement ce que considérez-vous "plus utilisable"? Personnellement, j'ai vraiment envie d'une recherche en texte intégral et une meilleure utilisation du navigateur, et l'AJAX aurait probable d'aide avec des personnes.
Bien, la bonne chose à propos de JavaDoc, c'est qu'il est à l'opposé de désuets, c'est de manière arbitraire extensible. Pourquoi ne pas aller de l'avant et d'écrire un doclet que produit le genre de doc API que vous voulez?
Pourquoi personne d'autre ne l'a fait jusqu'à présent (ce qui est apparemment le cas) je vous laisse deviner - peut-être que personne d'autre ne se sent que fortement à ce sujet que vous.
Il y a un DocBook doclet. DocBook est un riche type de document de (X)HTML et le mieux pour décrire le contenu technique. De DocBook source vous pouvez générer toutes sortes de différents formats de sortie.
Personnellement, je voudrais un plus lisible "commentaire de la documentation" standard que le HTML (et donc de tag-wieldy) JavaDoc.
Par exemple, MarkDown, tel qu'utilisé ici, serait excellent, lisible par l'homme dans la source, bien mis en forme externe de la source.
Avec le courant JavaDoc, j'imagine que beaucoup de gens utilisent des commentaires JavaDoc, mais ne fait pas de document dans la mesure où ils le pouvaient. Je suis sûr que tout le monde a parcouru une API en ligne de la JavaDoc qui a été non documentées ou peu documentées, et donc beaucoup plus difficile à utiliser que ce qu'elle devrait être.
Ce n'est pas aidé par code-reformatters (par exemple, au sein d'Eclipse, ou peut-être à la source de commettre) qui a totalement détruire tout lisible de la structure, vous pourriez avoir mis dans un commentaire JavaDoc (par exemple, une liste des éléments) dans une grosse goutte de texte, à moins que vous littéralement utiliser deux retours chariot où vous souhaitez utiliser l'un).
Le correspondant de la JSR (JSR 260), qui spécifie les améliorations apportées à Javadoc, a été démis de JDK 7 (pour l'instant). Un aperçu de ce qui était prévu (à partir de ce site):
Les perspectives de JDK 7 est assez sombres.
JavaDoc est lui-même extrêmement flexible car vous pouvez remplacer le doclet standard avec un doclet de fournir quelque chose qui répond à vos projets de besoins spécifiques.
Sur le projet que j'ai été travailler sur, nous avons créé un code HTML/XML et la documentation sur le système (à l'aide de client-côté XSLT 2.0 sur JS) pour notre produit avec JavaDoc entièrement intégré. Pour cela, une coutume doclet a été utilisé pour produire de la JavaDoc de données en XML, ce qui tagsoup pour assurer le balisage HTML dans les commentaires de code ont été bien formés.
Avec cela, nous avons été en mesure d'offrir une expérience utilisateur interactive à l'aide d'une seule page de l'app (similaire à un outil de bureau), mais le tout dans le navigateur - sans code côté serveur et de l'infrastructure. Le spectateur inclus en standard des fonctionnalités telles que la recherche, la navigation par arborescence etc.
Voici un lien vers un exemple de point d'entrée dans la vaste documentation:
JavaDoc exemple de visionneuse
Voici une image:
Une smart seachable javadoc viewer:
Pour de nombreuses fois, je suis face au problème de la navigation JavaDoc. J'étais à la recherche de quelque chose un peu comme Adnroid doc option de recherche. Enfin j'obtiens quelque chose comme ça. Si vous utilisez firefox, la solution est ici.
Installer le plugin GreaseMonkey, son un peu personnalisation de la page web de la façon dont nous le voyons. ( Nous avons besoin de personnaliser java page de doc, donc nous pouvons faire des recherches sur le nom de la classe)
https://addons.mozilla.org/en-US/firefox/addon/greasemonkey/
Pour greasemonkey pour travailler, nous avons besoin de quelques script utilisateur pour la personnalisation. Il peut être téléchargé par greasemonkey automatiquement. Installez le script de JavaDoc de recherche d'image ou JavaDoc de recherche incrémentale.
Cela fonctionne très bien pour moi.