Anleitung zum Schreiben eines API-Referenzdokuments

Bevor Sie mit der Dokumentation einer API beginnen, gibt es einige Dinge, die Sie vorbereiten und im Voraus planen sollten, bevor Sie tatsächlich mit dem Schreiben beginnen.

Es wird angenommen, dass Sie vor dem Lesen dieses Leitfadens über grundlegende Kenntnisse in folgenden Themen verfügen:

• Webtechnologien wie HTML, CSS und JavaScript. JavaScript ist dabei am wichtigsten.
• Verständnis und Lesen von Webtechnologie-Spezifikationen. Diese werden Sie häufig benötigen, während Sie APIs dokumentieren.

Alles andere kann unterwegs erlernt werden.

Bevor Sie mit der Dokumentation einer API beginnen, sollten Sie folgende Dinge zur Verfügung haben:

1. Die neueste Spezifikation: Ob es sich um eine W3C-Empfehlung oder einen frühen Entwurf eines Editors handelt, Sie sollten sich auf den neuesten verfügbaren Entwurf der Spezifikation beziehen, die die API abdeckt. Sie können diesen üblicherweise durch eine Websuche finden. Die neueste Version ist oft in einer Liste unter „LATEST DRAFT“ o. Ä. verlinkt.

2. Die neuesten modernen Web-Browser: Diese sollten experimentelle/Alpha-Builds sein, wie Firefox Nightly/Chrome Canary, die wahrscheinlich die von Ihnen zu dokumentierenden Features unterstützen. Dies ist besonders wichtig, wenn Sie eine neue/experimentelle API dokumentieren.

3. Demos/Blogposts/weitere Informationen: Sammeln Sie so viele Informationen wie möglich.

4. Nützliche technische Kontakte: Es ist hilfreich, einen freundlichen technischen Kontakt zu finden, um Fragen zur Spezifikation zu stellen, jemanden, der an der Standardisierung der API beteiligt ist oder an deren Implementierung in einem Browser arbeitet. Gute Orte, um solche Kontakte zu finden, sind:

   • Das interne Firmenadressbuch, falls Sie für ein relevantes Unternehmen arbeiten.
   • Eine öffentliche Mailingliste, die sich mit der Diskussion dieser API befasst, wie Mozillas dev-platform oder eine W3C-Liste wie public-webapps.
   • Die Spezifikation selbst. Zum Beispiel listet die Web Audio API-Spezifikation die Autoren und ihre Kontaktdaten oben auf.

Während der Dokumentation einer API werden Sie häufig Demos erstellen. Es ist jedoch sinnvoll, zunächst Zeit zu investieren, um sich mit der Funktionsweise der API vertraut zu machen — lernen Sie die Hauptinterfaces/-Eigenschaften/-Methoden kennen, die primären Anwendungsfälle und wie Sie einfache Funktionen damit schreiben können.

Wenn eine API geändert wurde, müssen Sie darauf achten, dass vorhandene Demos, auf die Sie sich beziehen oder von denen Sie lernen, nicht veraltet sind. Überprüfen Sie die Hauptstrukturen, die in der Demo verwendet werden, um sicherzustellen, dass sie der neuesten Spezifikation entsprechen. Sie könnten auch nicht in aktuellen Browsern funktionieren, aber dies ist kein sehr verlässlicher Test, da alte Features oft aus Gründen der Abwärtskompatibilität weiterhin unterstützt werden.

Eine API-Referenz enthält in der Regel die folgenden Seiten. Details, Beispiele und Vorlagen, was jede Seite enthält, finden Sie in unserem Artikel Seitentypen. Bevor Sie beginnen, sollten Sie eine Liste aller Seiten erstellen, die Sie anlegen müssen.

1. Übersichtsseite
2. Interface-Seiten
3. Konstruktor-Seiten
4. Methoden-Seiten
5. Eigenschafts-Seiten
6. Ereignisse-Seiten
7. Konzept-/Leitfaden-Seiten
8. Beispiele

Übersichtsseiten

Eine einzelne API-Übersichtsseite beschreibt die Rolle der API, ihre obersten Interfaces, verwandte Funktionen, die in anderen Interfaces enthalten sind, sowie andere Details auf hoher Ebene. Der Name und der Slug der Seite sollten der Name der API mit „API“ am Ende sein. Sie befindet sich auf oberster Ebene der API-Referenz, als Kind von https://developer.mozilla.org/de/docs/Web/API.

Beispiel:

• Titel: Web Audio API
• Slug: Web_Audio_API
• URL: https://developer.mozilla.org/de/docs/Web/API/Web_Audio_API

Interface-Seiten

Jedes Interface hat ebenfalls eine eigene Seite, die den Zweck des Interfaces beschreibt, alle Mitglieder (Konstruktoren, Methoden, Eigenschaften usw., die sie enthält) auflistet und zeigt, mit welchen Browsern es kompatibel ist. Der Name und der Slug einer Seite sollten dem Namen des Interfaces entsprechen, genau wie in der Spezifikation geschrieben. Jede Seite wird auf der obersten Ebene der API-Referenz platziert, als Kind von https://developer.mozilla.org/de/docs/Web/API.

Beispiele:

• Titel: AudioContext
• Slug: AudioContext
• URL: https://developer.mozilla.org/de/docs/Web/API/AudioContext

• Titel: AudioNode
• Slug: AudioNode
• URL: https://developer.mozilla.org/de/docs/Web/API/AudioNode

• Methoden, die auf der Prototyp-Klasse eines Interface-Objekts definiert sind (Instanzmethoden), und Methoden, die auf der eigentlichen Klasse selbst definiert sind (statische Methoden), werden dokumentiert. Wenn beide selten auf demselben Interface existieren, sollten Sie sie in separaten Abschnitten auf der Seite auflisten (statische Methoden/Instanzmethoden). Üblicherweise existieren nur Instanzmethoden, in diesem Fall können Sie diese unter dem Titel „Methoden“ zusammenfassen.
• Geerbte Eigenschaften und Methoden des Interfaces werden nicht dokumentiert: Sie werden im jeweiligen übergeordneten Interface aufgelistet. Allerdings wird auf ihre Existenz hingewiesen.
• Eigenschaften und Methoden, die in Mixins definiert sind, werden dokumentiert. Weitere Details finden Sie im Beitrags-Leitfaden für Mixins.
• Spezielle Methoden wie der Stringifier (toString()) und der Jsonifier (toJSON()) werden ebenfalls aufgeführt, wenn sie existieren.
• Benannte Konstruktoren (wie Image() für HTMLImageElement) werden ebenfalls aufgeführt, falls relevant.

Konstruktor-Seiten

Jedes Interface besitzt null oder einen Konstruktor, der auf einer Unterseite der Interface-Seite dokumentiert ist. Es beschreibt den Zweck des Konstruktors und zeigt dessen Syntax, Anwendungsbeispiele, Browser-Kompatibilitätsinformationen usw. Sein Slug ist der Name des Konstruktors, der genau dem Interface-Namen entspricht, und der Titel ist Interface-Name, Punkt, Konstruktor-Name, dann Klammern am Ende.

Beispiel:

• Titel: AudioContext.AudioContext()
• Slug: AudioContext
• URL: https://developer.mozilla.org/de/docs/Web/API/AudioContext/AudioContext

Eigenschaftsseiten

Jedes Interface besitzt null oder mehr Eigenschaften, die auf Unterseiten der Interface-Seite dokumentiert sind. Jede Seite beschreibt den Zweck der Eigenschaft und zeigt deren Syntax, Nutzungsbeispiele, Browser-Kompatibilitätsinformationen usw. Der Slug ist der Name der Eigenschaft, der Titel ist Interface-Name, Punkt, dann Eigenschaftsname.

Beispiele:

• Titel: AudioContext.state
• Slug: state
• URL: https://developer.mozilla.org/de/docs/Web/API/AudioContext/state

Methoden-Seiten

Jedes Interface besitzt null oder mehr Methoden, die auf Unterseiten der Interface-Seite dokumentiert sind. Jede Seite beschreibt den Zweck der Methode und zeigt deren Syntax, Dateibeispiele, Browser-Kompatibilitätsinformationen usw. Der Slug entspricht dem Namen der Methode, und der Titel ist Interface-Name, Punkt, Methodenname, dann Klammern.

Beispiele:

• Titel: AudioContext.close()
• Slug: close
• URL: https://developer.mozilla.org/de/docs/Web/API/AudioContext/close

• Titel: AudioContext.createGain()
• Slug: createGain
• URL: https://developer.mozilla.org/de/docs/Web/API/AudioContext/createGain

[Die Übersetzung wird fortgesetzt, erforderlichenfalls ergänzen Sie die Inhalte].