mise à jour 2019-09-29 : Java version 11
La technique ci-dessous ne fonctionne pas maintenant avec Java 11, et probablement les versions supérieures : il n'y a aucun moyen d'ignorer les multiples "liens brisés" (c'est-à-dire vers d'autres classes, d'autres API). Solution : gardez votre fichier exécutable javadoc (ou javadoc.exe) de la version 8 de Java
Il y a de bonnes raisons de créer vos propres javadocs locales, et ce n'est pas particulièrement difficile !
D'abord, vous avez besoin de la source. Au moment de l'écriture, le JDK de Java 8 est livré avec un fichier zip appelé src.zip
. Parfois, pour des raisons inexpliquées, Oracle n'inclut pas toujours la source. Ainsi, pour certaines versions plus anciennes (et qui sait pour l'avenir), vous devez vous procurer la source Java d'une autre manière. Il faut également savoir que, dans le passé, Oracle a parfois inclus la source avec la version Linux du JDK, mais pas avec celle de Windows.
Je viens de décompresser ce fichier... les premiers répertoires sont "com", "java", "javax", "launcher" et "org". Répertoire launcher
ne contient aucun fichier à documenter.
Vous pouvez générer les javadocs très très simplement à partir de n'importe lequel ou de tous ces documents en plaçant le CD à l'invite de commande/terminal dans le répertoire ...\src
. Ensuite, allez
javadoc -d docs -Xmaxwarns 10 -Xmaxerrs 10 -Xdoclint:none -sourcepath . -subpackages java:javax:org:com
Notez qu'il y a un "." après le nom de l'entreprise. -sourcepath
C'est aussi simple que cela. Générer vos propres javadocs présente également deux avantages considérables
- vous savez que ce sont précisément les bonnes javadocs pour le JDK (ou tout autre fichier jar externe) que vous utilisez sur votre système.
- une fois l'habitude prise, reconstituer vos Javadocs n'est pas un défi fastidieux (i.e. où aller les chercher). Par exemple, j'ai juste décompressé un couple de jars sources dont les paquets sont étroitement couplés, de sorte que leurs sources ont été en fait "fusionnées" & puis j'ai fait une seule Javadoc à partir d'eux...
NB Swing est semi-officiellement MORT. Nous devrions tous passer à JavaFX, qui est utilement fourni avec le JDK de Java 8, mais dans son propre fichier source, javafx-src.zip
.
Une fois décompressé, il révèle 3 paquets "Root" : com
, javafx
y netscape
(wha' ?). Ceux-ci doivent être déplacés manuellement à l'endroit approprié sous le fichier dézippé src
(y compris le répertoire JavaFX com.sun
sous le nom de Java com.sun
strcture). La compilation de tous ces fichiers Javadoc a pris un temps non négligeable à ma machine. Je m'attends à voir toutes les classes sources JavaFX avec toutes les autres classes sources dans un avenir proche.
BTW, la même réflexion s'applique à la documentation de tous les jars Java (avec les sources) que vous utilisez. Cependant, vous trouverez toutes les versions de la plupart des jars avec leur documentation disponible en téléchargement sur Maven Central. http://search.maven.org ...
PS après coup :
à l'aide d'Eclipse et du plugin "Gradle STS" : l'assistant "New Gradle STS Project" créera un gradle.build
contenant la ligne
include plugin: 'eclipse'
Cela télécharge comme par magie le jar source avec le jar exécutable (sous la rubrique GRADLE_HOME
) quand vous allez
./gradlew build
[addendum 2020-01-13 : si vous avez choisi de ne pas inclure le plugin Eclipse dans votre build.gradle, il semblerait que vous puissiez aller (avec la sélection sur votre projet dans l'Explorateur de projet) Clic-droit Gradle
--> Refresh Gradle Project
pour qu'Eclipse télécharge les fichiers sources].
... vous donnant un degré supplémentaire de certitude que vous avez obtenu le bon produit. src
et donc le droit javadoc
pour la dépendance en question.