Als ich in die Forschung ging, verschob sich mein Programmieralltag von Java zu Python. Besonders ungewohnt dabei war, dass die Dokumentation der Standardbibliothek wie ein Handbuch geschrieben ist, organisiert in Seiten und Kapiteln. Ich meine hier kein Tutorial, sondern die API-Referenzdokumentation. Dieses Muster findet man fast in der ganzen Pythonwelt, einschließlich prominenter Bibliotheken wie NumPy und SciPy. Java-APIs werden in der Regel als strukturierte Systeme präsentiert, organisiert nach Paketen und Klassen, die sich entsprechend erkunden lassen.
Um das klar zu sagen: Die Pythondokumentation ist umfangreich und von hoher Qualität. Dennoch begünstigt das vorherrschende Interaktionsmodell Suche und sequentielles Lesen gegenüber systematischer Exploration. Immer wieder sehe ich Java-Entwickler Python als „schlecht dokumentiert“ bezeichnen und ich glaube, dass damit oft die fehlende strukturelle Sichtbarkeit gemeint ist. Der Blick außerhalb des Java-Ökosystems machte dieses Problem sichtbarer und führte zu einer grundsätzlichen Frage:
Was für ein System sollte eine API-Referenzdokumentation eigentlich sein?
Motivation
API-Referenzdokumentation und Handbücher erfüllen unterschiedliche Aufgaben, doch modernes Web-Publishing verwischt diese Unterscheidung zunehmend. Das ist ein Kategorienfehler.
Lineare Dokumentation eignet sich hervorragend für Tutorials, Einarbeitung und konzeptionelle Erläuterungen. Sie setzt eine Leserichtung voraus und führt entlang vorgegebener Pfade. API-Referenzdokumentation hingegen beschreibt ein System. Sie beantwortet Fragen wie:
- Was stellt diese API bereit?
- Wie ist sie strukturiert?
- Welche Elemente gehören zusammen?
- Wo fügt sich ein bestimmter Typ in das Gesamtbild ein?
Solche Fragen lassen sich mit linearem Text nur unzureichend beantworten. Sie erfordern eine Darstellung, die die Struktur der Codebasis selbst widerspiegelt: Pakete, Module, Namespaces, Klassen und ihre Beziehungen. Historisch hat Java diese Unterscheidung gut geleistet. Klassisches Javadoc machte die Struktur unübersehbar. Vergleichbare Ansätze gab und gibt es auch anderswo: in der MSDN Bibliothek, in hierarchisch organisierten Unix-Manpages oder in den angepassten Javadocs von Android. Diese Systeme präsentieren API-Dokumentation als Raum, der erkundet werden kann.
Im Laufe der Zeit wurde API-Dokumentation zunehmend an seitenorientiertes Web-Publishing angepasst. In Java verschwanden mit den Frames zwar nicht die strukturellen Elemente wie Übersichtsseiten von Paketen und Modulen, Breadcrumbs oder Indizes, wohl aber ihre unmittelbare Präsenz. Die Navigation verlagerte sich von Exploration hin zu gezieltem Nachschlagen. Sprachübergreifend wird dieser Effekt noch deutlicher. In Python ist lineare Dokumentation die Norm. Selbst Kernbibliotheken sind schwer zugänglich, wenn man nicht bereits weiß, wonach man suchen muss. Für Einsteiger ist es schwierig, das Vorhandene zu entdecken.
Die Plattform javadoc.io verbessert die Zugänglichkeit von Javadoc, indem sie es direkt im Web bereitstellt. Als Mirror von Maven Central-Inhalten veröffentlicht sie jedoch schlicht das, was Projekte dort hochladen. So stehen Dokumentationen, die über Jahrzehnte hinweg entstanden sind, nebeneinander – teils mit Frames, teils ohne, teils mit sehr altem CSS.
APIdia (apidia.net) basiert auf der Idee, API-Dokumentation als first-class Artefakt zu behandeln, das die Struktur einer Codebasis widerspiegelt. Moderne Webtechnologie sollte gerade eingesetzt werden, um dieses Konzept zu stärken und weiterzuentwickeln. Visuell orientiert sich APIdia an Javadoc, adressiert dabei aber langjährige Painpoints und bietet konsistente Navigation über Projektgrenzen hinweg. Ziel ist es, API-Referenzdokumentation wieder in ihre eigentliche Rolle zu rücken: als strukturierte, explorierbare Repräsentation eines Softwaresystems, die Tutorials und Handbücher beim Verstehen, Lernen und Lehren ergänzt.
Bestandsaufnahme
Als ich mit der Arbeit an APIdia begann, war der erste Schritt eine technologische Bestandsaufnahme. Doxygen, der bekannte API-Dokumentationsgenerator, war dabei der heißeste Kandidat. Er unterstützt zahlreiche Sprachen, darunter Java, Python und C++, kann Bibliotheken miteinander verlinken und erzeugt HTML-, PDF- sowie XML-Ausgaben. Da Doxygen als Alternative zu Javadoc betrachtet wird, mögen die folgenden Ergebnisse für manche überraschend sein.
Auch wenn Sphinx kein Java-Werkzeug ist, wäre eine solche Bestandsaufnahme ohne einen Blick auf das Standard-Dokumentationswerkzeug der Pythonwelt unvollständig. Über Python hinaus findet Sphinx Anwendung bei vielen etablierten Projekten wie z.B. LLVM. Während APIdia mit Java beginnt, bleibt Python ein zukünftiges Ziel und Sphinx liefert die Basis dafür.
Werkzeuge wie Asciidoctor, Dokka oder Scaladoc sind ebenfalls relevant, würden jedoch den Rahmen dieses Artikels sprengen.
Doxygen
Doxygen ist ein ausgereiftes Tool für strukturierte API-Dokumentation. In meinen Experimenten habe ich es mit Mengen von Java-Code strapaziert, u.A. aus der Standardbibliothek. Probleme wurden konsequent im Issuetracker registriert und teils mit den Entwicklern diskutiert. Vieles wurde rasch behoben, was ich sehr wertschätze. Drei zentrale Probleme bleiben jedoch ungelöst:
- Annotations, zentral für modernes Java, werden oft nicht erkannt: #7335, #9118.
- Verschachtelte Generics bringen den Parser durcheinander und führen zu unvollständiger Ausgabe: #8495.
- Fehlerhaftes HTML in Doc-Kommentaren kann verursachen, dass der Parser das Ende des Kommentars übergeht und nachfolgenden Code in die Dokumentation leakt: #8618.
Diese Probleme sind teils auf die ursprünglich für C++ gedachte Architektur zurückzuführen, machen Doxygen jedoch für modernes Java ungeeignet. Die XML-Ausgabe bietet allerdings eine mögliche Grundlage für spätere C++-Unterstützung in APIdia.
@NotNull Method-Annotations.Im Standard-HTML-Layout von Doxygen basiert die Navigation auf einer klappbaren Baumansicht, die gut die Hierarchie darstellt. Da das Auf- und Zuklappen den Sichtbereich stark verschiebt, ist es oft nötig umherzuscrollen, auch horizontal. Klappbare Knoten machen die GUI zustandsintensiv, was Komplexität und Entscheidungen mit sich bringt: Sollte der Zustand im Browser gespeichert oder bei jedem Besuch zurückgesetzt werden?
Sphinx
In Sphinx ist die zentrale Organisationseinheit das Dokument, nicht die Codestruktur. Autoren verfassen reStructuredText- oder Markdown-Dateien und definieren ein Inhaltsverzeichnis, das diese in eine Gesamt-Dokumentation zusammenführt.
Mittels der Erweiterung autodoc lassen sich API-Elemente aus dem Quellcode flexibel und nahtlos in Dokumente wie Tutorials integrieren. In neueren Sphinx-Versionen kann die apidoc-Erweiterung aus der Codebasis auch automatisch API-Elemente im Inhaltsverzeichnis auflisten. In der Praxis nutzen viele Projekte diese Automatisierung noch nicht und integrieren API-Dokumentation über autodoc direkt in ihr Handbuch. Als ein Nachteil ist zu nennen, dass Sphinx generell keine Summary-Sektionen generiert, wie man sie aus Javadoc kennt. Dies kann die Orientierung in großen Modulen erschweren.
Durch das Template-System variieren Layout und visuelle Identität stark zwischen Projekten. Dass die Navigation bei den Standard-Themes gekoppelt mit dem Hauptinhalt scrollt, ist für die Nutzung nicht immer ideal. Unabhängiges scrollen ist nur durch manuelle Anpassung von CSS oder Verwendung von Drittanbieter-Themes wie PyData oder ReadTheDocs möglich.
Übrigens gab es einst Java-Unterstützung für Sphinx. Die Erweiterung javasphinx ist inzwischen jedoch unmaintained und benötigte eine von Sphinx unterstützte Markup-Sprache in Doc-Kommentaren. Die ausgereifte Infrastruktur um Sphinx, z.B. die Bibliotheken docutils und Napoleon, werden für eine Python-Unterstützung in APIdia eine wichtige Rolle spielen.
Konsequenzen für APIdia
Aus der Evaluation ergeben sich konkrete Entscheidungen:
- keine einklappbare Baum-Navigation in APIdia
- unabhängiges Scrollen von Navigation und Inhaltsbereich, nie horizontal
- Minimierung von Zustand, sodass er in URLs repräsentiert werden kann
- Javas eigene Infrastruktur wird zum Parsen benutzt
(Modulejava.compiler,jdk.compiler,jdk.javadoc)
Architekturprinzipien von APIdia
Die visuelle Nähe zu Javadoc hat einen nostalgischen Effekt, der zwar nicht unerwünscht ist, aber keineswegs das primäre Designziel darstellt. Vielmehr ergibt sich die Darstellung aus fundamentalen Abwägungen als natürliche Lösung.
Die Herausforderung ist, Navigationseinheiten so zu definieren, dass sie sprachübergreifend tragfähig sind. Java kennt Module, Pakete und Klassen; Python ordnet Module zwischen Paketen und Klassen ein; C++ ist in Headern und Namespaces organisiert. Anstatt eine einzelne Abstraktion zu bevorzugen, kann auf die physische Struktur des Quellcodes als universelles Organisationsprinzip zurückgegriffen werden.
Dateien und Verzeichnisse bilden ein sprachunabhängiges Modell und Entwickler achten in der Regel auf ausgewogene Verzeichnisstrukturen und handhabbare Dateigrößen. Die Idee ist nicht einfach, einen Dateibrowser zu bauen, sondern dass die Einteilung von Programmelementen in Verzeichnischarakter und Dateicharakter eine balancierte Organisationsstruktur liefert. Dies führt zu drei konzeptionellen Ebenen: Verzeichnisse, Dateien und Inhalt.
In Java besitzen Module und Pakete Verzeichnischarakter, während Top-Level-Klassen als dateiartige Einheiten behandelt werden. Innere Klassen gehören zum Inhalt ihrer umschließenden Typen. In Python entsprechen Pakete den Verzeichnissen und Module den Dateien, aber trotz unterschiedlicher Zuordnung bleibt das Organisationsprinzip gleich.
Stabilität hat Priorität
Die drei Ebenen – Verzeichnisse, Dateien, Inhalt – entsprechen in natürlicher Weise der dreigeteilten Ansicht von klassischem Javadoc. Die Oberfläche von APIdia setzt dieses Modell in drei persistenten Bereichen um. Oben links werden verzeichnisartige Elemente angezeigt, einschließlich eines projektweiten „Overview“-Eintrags. Unten links erscheint der Inhalt des aktiven Verzeichnisses in einer stabilen Listenansicht anstelle eines klappbaren Baums. Einträge mit Verzeichnischarakter sind durch einen Pfeil gekennzeichnet: Der Pfeil öffnet das Verzeichnis, der Name lädt den Inhalt. Damit wird die Doppelnatur von Java-Paketen (package-info.java), Java-Modulen (module-info.java) oder Python-Paketen (__init__.py) aufgelöst.
Der Hauptbereich zeigt stets genau eine dateiartige Einheit an mit moderater In-Page-Navigation auf der rechten Seite. Die Vermeidung von Zustandslast setzt sich fort: Genau wie Bäume würden auch ausklappbare Detailansichten Zustand beisteuern. Daher wird das aus Javadoc bekannte Summary/Detail-Muster beibehalten, aber um ein wichtiges Feature ergänzt: Jede Detailsektion erhält einen Rücklink auf ihren Summary-Eintrag. Diese Anpassung ermöglicht effektiv das gleiche Nutzungsmuster wie kollabierbare Ansichten, ohne weiteren Zustand einzuführen.
Sichtbarkeit und Filterung
Die Dokumentation wird grundsätzlich mit vollständiger Abdeckung erzeugt: Alle Typen und Members sind enthalten und ihre Sichtbarkeit wird auf Darstellungsebene gesteuert. Interne Elemente sind standardmäßig ausgeblendet und lassen sich nach folgenden Kriterien einblenden und filtern:
- Zugriff (
publicbisprivate) - Modul-Exposition (
exported,opened, intern) - Modulauswahl
Dass durch die Filterung nun doch eine gewisse Zustandslast eingeführt wird, ist eine sorgfältige Abwägung und bleibt gerade dadurch handhabbar, dass Zustand an anderen Stellen vermieden wird. Um interne API mit Javadoc darzustellen, würde man das private Flag verwenden, was aber die Interna fest integriert. APIdias konfigurierbare Ansicht hingegen bedient Nutzungsmuster von Maintainern und Anwendern in einer einzigen Einheit.
Maven-Artefakte und Module
Javas Modulsystem stellt eine parallele Organisationsstruktur zu Maven-Artefakten dar. Um dies aufzulösen, behandelt APIdia Maven-Artefakte grundsätzlich als Module. Existiert ein deklariertes Java-Modul im Artefakt, wird dieses verwendet; andernfalls wird das Artefakt als automatisches Modul dargestellt und gekennzeichnet. So bleibt die Navigation einheitlich, ohne Maven als zusätzliche Abstraktionsebene einführen zu müssen.
Projekte umfassen häufig mehrere Artefakte, deren isolierte Darstellung zu Fragmentierung führen würde. Da Maven kein zuverlässiges Prinzip zur Gruppierung von Artefakten in sinnvolle Projekteinheiten bietet, kommen heuristische Ansätze zum Einsatz: gemeinsame Versionsstände innerhalb einer Group-ID, BOM-Dateien oder Parent-Artefakte. Einige Projekte, z.B. OSGi, exponieren keine dieser Strukturen auf Maven-Ebene, sodass manuelle Kuratierung erforderlich ist.
Diese Aggregation ist ein wichtiger Unterschied zu javadoc.io, das Artefakte isoliert spiegelt. Während dort z.B. jackson-databind als eigenständige Einheit erscheint, integriert APIdia es in den Gesamtkontext des Jackson-Projekts und stellt alle zugehörigen Module in einem konsistenten Navigationsmodell dar.
Projektübergreifende Verlinkung
Die Ambition, dass möglichst kein referenziertes Element unverlinkt bleibt, setzt im Prinzip voraus, dass der vollständige Abhängigkeitsbaum eines Projekts verfügbar sein muss. In der Praxis wird dies zur Herausforderung, da die Bäume sehr groß sein können. Ein vollständiges Spiegeln von Maven Central ist dabei weder realistisch noch sinnvoll. Neben dem schieren Umfang ist zu beachten, dass viele Artefakte eher stören würden: sehr alte Versionen, experimentelle Projekte und aufgegebene Forks.
APIdia geht daher selektiv und inkrementell vor. Beginnend bei etablierten Projekten wie Jakarta EE, Spring, Apache Commons und vielen weiteren, werden Abhängigkeitsbäume rückwärts abgearbeitet, sodass eine Art kanonische Untermenge des Ökosystems entsteht. Nutzer können fehlende Projekte als neue Ankerpunkte für dieses System einbringen.
Fazit
Handbücher und API-Dokumentation profitieren von unterschiedlichen Strukturen, die dem jeweiligen mentalen Modell gerecht werden. API-Dokumentation funktioniert am besten, wenn sie nah am Code orientiert ist, denn die Struktur ist Teil der Dokumentation. Ein geeignetes Navigationsmodell sollte diesen Zusammenhang unterstützen und abbilden. Der Vergleich von Javadoc, Doxygen und Sphinx zeigt, dass Werkzeuge prägend für die Dokumentationskultur sind. Konventionelles Web-Publishing wird der hierarchischen Struktur von API-Dokumentation selten gerecht und wenn, dann nur mit erheblichem Anpassungsaufwand.
Mit APIdia wird eine Plattform angeboten, die explizit für strukturierte, hierarchische API-Dokumentation konzipiert ist. Etablierte Konventionen werden nicht abgeschwächt, sondern weiterentwickelt und generalisiert. Durch projektübergreifende Verlinkung entsteht eine konsistente, erkundbare Repräsentation im Maßstab eines ganzen technischen Ökosystems.
