Das javadoc-Tool hat die Aufgabe, den Java-Quellcode auszulesen und die Javadoc-Kommentare zu extrahieren. Was dann mit den Daten passiert, ist die Aufgabe eines Doclets. Das Standard-Doclet von Oracle erzeugt die bekannte Struktur auf verlinkten HTML-Dateien, aber es lassen sich auch eigene Doclets schreiben, um etwa in Javadoc-Kommentaren enthaltene Links auf Erreichbarkeit zu prüfen oder UML-Diagramme aus den Typbeziehungen zu erzeugen. Hervorzuheben ist JDiff (http://javadiff.sourceforge.net/), was Differenzen in unterschiedlichen Versionen der Java-Dokumentation – wie neu hinzugefügte Methoden – erkennt und meldet.
Die Doclet-API ist Teil vom JDK, und deklariert Typen und Methoden, mit denen sich Module, Pakete, Klassen, Methoden usw. und deren Javadoc-Texte erfragen lassen. Allerdings gibt es zwei Doclet-APIs:
- Im Paket javadoc.doclet (Modul jdk.javadoc) ist die aktuelle API.
- Im Paket sun.javadoc ist die mittlerweile deprecated API, allerdings einfacher zu nutzen.
Beispiel
Im folgenden Beispiel wollen wir ein kleines Doclet schreiben, das Klassen, Attribute, Methoden und Konstruktoren ausgibt, die das Javadoc-Tag @since 10 tragen. So lässt sich leicht ermitteln, was in der Version Java 10 alles hinzugekommen ist. Doclets werden normalerweise von der Kommandozeile aufgerufen und dem javadoc-Tool übergeben, doch da es mit der Tool-Schnittstelle auch selbst geht, können wir ein Programm mit main(…)-Methode schreiben, das die Neuerungen auf der Konsole ausgibt.
package com.tutego.insel.tools;
import java.io.IOException;
import java.nio.file.*;
import java.util.Arrays;
import java.util.List;
import java.util.function.Predicate;
import java.util.stream.Collectors;
import javax.tools.*;
import com.sun.javadoc.*;
@SuppressWarnings( "deprecation" )
public class FindSinceTagsInJavadoc {
public static class TestDoclet {
public static boolean start( RootDoc root ) {
Arrays.stream( root.classes() ).forEach( TestDoclet::processClass );
return true;
}
private static void processClass( ClassDoc clazz ) {
Predicate<Doc> hasSinceTag = doc -> Arrays.stream( doc.tags( "since" ) )
.map( Tag::text ).anyMatch( "10"::equals );
if ( hasSinceTag.test( clazz ) )
System.out.printf( "%s -- Neuer Typ%n", clazz );
Arrays.stream( clazz.fields() ).filter( hasSinceTag )
.forEach( f -> System.out.printf( "%s -- Neues Attribut%n", f ) );
Arrays.stream( clazz.methods() ).filter( hasSinceTag )
.forEach( m -> System.out.printf( "%s -- Neue Methode%n", m ) );
Arrays.stream( clazz.constructors() ).filter( hasSinceTag )
.forEach( c -> System.out.printf( "%s -- Neuer Konstruktor%n", c ) );
}
}
public static void main( String[] args ) throws IOException {
Path zipfile = Paths.get( System.getProperty( "java.home" ), "lib/src.zip" );
try ( FileSystem srcFs = FileSystems.newFileSystem( zipfile, null ) ) {
Predicate<Path> filesToIgnore = p -> p.toString().endsWith( ".java" ) &&
! p.toString().startsWith( "/javafx" ) &&
! p.toString().startsWith( "/jdk" ) &&
! p.toString().endsWith( "module-info.java" ) &&
! p.toString().endsWith( "package-info.java" );
List<Path> paths = Files.walk( srcFs.getPath( "/" ) )
.filter( filesToIgnore ).collect( Collectors.toList() );
DocumentationTool tool = ToolProvider.getSystemDocumentationTool();
try ( StandardJavaFileManager fm = tool.getStandardFileManager( null, null, null ) ) {
Iterable<? extends JavaFileObject> files = fm.getJavaFileObjectsFromPaths( paths );
tool.getTask( null, fm, null, TestDoclet.class, List.of( "-quiet" ), files ).call();
}
}
}
}
Unsere main(…)-Methode bindet zunächst das ZIP-Archiv vom JDK mit den Quellen als Dateisystem ein. Im nächsten Schritt durchsuchen wir das Dateisystem nach den passenden Quellcodedateien und sammeln sie in eine Liste von Pfaden. Jetzt kann das DocumentationTool mit unserem Doclet konfiguriert und aufgerufen werden. call() startet das Parsen aller Quellen und führt anschließend zum Aufruf von start(RootDoc) unseres Doclets.
In unserer start(…)-Methode laufen wir über alle ermittelten Typen und rufen dann processClass(ClassDoc) auf. Dort passiert der eigentliche Test. Die Metadaten kommen dabei über diverse XXXDoc-Typen. Ein Predicate zieht den Tag-Test heraus.