mozilla

Version 112191 von Schreiben der Interface Dokumentation

  • Adressname der Version: Project:Schreiben_der_Interface_Dokumentation
  • Titel der Version: Schreiben der Interface Dokumentation
  • ID der Version: 112191
  • Erstellt:
  • Autor: fscholz
  • Aktuelle Version? Nein
  • Kommentar 23 words added
Schlagwörter: 

Inhalt der Version

{{ MDCProjectPagesTOC() }}

Dieser Artikel verdeutlicht wie man ordnungsgemäß formatierte und nützliche Dokumentationsseiten für Schnittstellen schreibt. Jedes Interface sollte in einem eigenen Artikel dokumentiert werden, der Titel ist dabei der Name der Schnittstelle.

Anhand eines Beispiels lernen

Das Beispiel Interface zeigt ein ausgedachtes Interface, welches ein Beispiel für eine komplette Schnittstellenreferenz darstellt. Dieser Beispielartikel kann sehr hilfreich zur Dokumentation von Schnittstellen sein.

Wirkliche Schnittstellen, die gut dokumentiert sind, sind zum Beispiel: nsIFeedProcessor, nsIFeedContainer, nsIFeedTextConstruct und nsIScriptableUnescapeHTML.

Abschnitte in der Schnittstellenreferenz

Jede Schnittstellenreferenz hat wenigsten eine Einleitung (welche keine Überschrift trägt). Die Einleitung sollte einen Überblick darüber liefern, wofür das Interface benutzt wird.

Nach dem Inhaltsverzeichnis wird die InterfaceStatus Vorlage verwendet, um den Ort sowie den Status der Schnittstelle anzugeben.

Die Parameter der {{InterfaceStatus}} Vorlage sind:

  • Der Schnittstellenname
  • Der Pfad zur IDL Datei für das Interface (z.B. xpcom/ds/nsIObserver.idl)
  • "FROZEN" oder "unfrozen" abhängig davon, ob das Interface entweder das eine oder das andere ist.
  • Die Mozilla-Version, in der das Interface zuletzt geändert wurde (zum Beispiel "Mozilla 1.8")
  • "yes" wenn das Interface skriptbar ist oder "no" falls das nicht der Fall ist

Schließlich sollte eine "Erbt von:" Zeile vorhanden sein, die die Elternschnittstellen auflistet. Genau so sollte eine Zeile "Implementiert von:" vorhanden sein, die die Schnittstellen auflistet, die von diesem Interface abgeleitet werden.

Alle weiteren Abschnitte sind optional und ob diese benötigt werden, variiert von Interface zu Interface. Die optionalen Abschnitte sind:

Methodenüberblick

Der Methodenüberblick besteht aus einer Tabelle, die einfach alle Methoden für das Interface auflistet. Der Methodenname sollte ein Link sein, welcher auf die Methode selbst verweist. Am Besten werden die Methoden alphabetisch aufgelistet.

Wenn eine Methode mehrere Typen für einen Eingabeparameter unterstützt, können die über das Format [type1, type2, ..., typeN] unterschieden werden.

Attribute

Der Abschnitt zu den Attributen besteht aus einer drei-spaltigen Tabelle. Die erste Spalte enthält den Namen jedes Attributs. Die zweite Spalte gibt den Typen jedes Attributs an (bei nicht trivialen Typen sollte ein Link zu einer erklärenden Seite gesetzt werden). Die dritte Spalte beschreibt das Attribut in dem die Verwendung und weitere Details angegeben werden. Attribute sollten in alphabetischer Reihenfolge notiert werden.

Konstanten

Jede Gruppe von Konstanten sollte einen Unterabschnitt besitzen, der eine Tabelle enthält, welche die relevanten Konstanten beschreibt. Die Tabelle sollte drei Spalten haben: Konstante (Namen der Konstanten), Wert (die Werte) und Beschreibung (beschreibender Text; Erklärung).

Methoden

Der Abschnitt zu den Methoden liefert detaillierte Dokumentation für jede Methode der Schnittstelle. Innerhalb des Methodenabschnitts sollte ein Unterbereich für jede einzelne Methode bereitgestellt werden. Jeder Methodenabschnitt sollte nach dem Methodennamen mit Klammern benannt werden (so wie "parseAsync()" in der {{ Interface("nsIFeedProcessor") }} Schnittstellenreferenz.

Die Methoden sollten in der selben Reihenfolge aufgeführt werden, wie sie auch im "Methodenüberblick" genannt werden.

Jeder Methodenabschnitt sollte wieder mit einer Beschreibung anfangen, gefolgt von der Methodensignatur selbst. Jeder Parameter sollte in einer einzelnen ZEile aufgeführt werden, sodass diese leicht zu erkennen sind.

Nach der Methodensignatur sollte ein Parameterabschnitt folgen. Damit das Inhaltsverzeichnis der Seite nicht unnötig lang wird, nutzen wir <h5>Parameter</h5>, um die Überschriften der Parameter zu definieren.

Die Parameter werden dann mit ihren Beschreibungen in Definitionslisten aufgeführt. Wenn keine Parameter vorhanden sind, wird einfach 'Keine' unter der Parameterüberschrift geschrieben.

Falls eine Methode einen Rückgabewert hat, wird ein Abschnitt <h5>Rückgabewert</h5> hinzugefügt. Dieser Teilabschnitt sollte einfach nur den Rückgabewert erklären, den Typ nennen und eventuell geläufige Rückgabewerte aufzählen.

Falls eine Methode Exceptions auswerfen kann, wird ein "Exceptions" Abschnitt hinzugefügt, welcher eine Definitionsliste mit möglichen Exceptions enthält.

Ein gutes Beispiel, welches all diese Teilabschnitte enthält, siehe {{ Interface-method("nsIScriptableUnescapeHTML", "parseFragment") }}.

Bemerkungen

Etwaige Kommentare zur Schnittstelle als Ganzes können unter "Bemerkungen" aufgeführt werden.

Siehe auch

Hilfreiche Links zu anderen Schnittstellen oder Dokumenten sollten in einem "Siehe auch" Abschnitt notiert werden.

Artikel kategorisieren

Jeder Artikel, der ein Interface dokumentiert muss mit dem Tag "Interfaces" versehen werden. Weitere passende Tags sollten außerdem gesetzt werden.

Weitere hilfreiche Vorlagen

Verwenden Sie MDC: Spezielle Vorlagen wenn passend, speziell Template:interface, wenn Sie auf andere Schnittstellen verlinken und Template:interface-method wenn Sie auf eine bestimmte Methode einer Schnittstelle verlinken.

Artikel finden, die noch verbessert werden können

Schauen Sie durch die Liste der Schnittstellen und überprüfen Sie, ob welche in der Kategorie NeedsMarkupWork markiert wurden. Das sind Schnittstellen von denen wir wissen, das sie noch durch dieses Layout formatiert werden müssen. Wenn Sie eines verbessert haben, entfernen Sie den Tag entsprechend.

{{ languages( { "en": "Project:en/Writing_interface_reference_documentation" } ) }}

Quelltext der Version

<p>{{ MDCProjectPagesTOC() }}</p>
<p>Dieser Artikel verdeutlicht wie man ordnungsgemäß formatierte und nützliche Dokumentationsseiten für Schnittstellen schreibt. Jedes Interface sollte in einem eigenen Artikel dokumentiert werden, der Titel ist dabei der Name der Schnittstelle.</p>
<h3>Anhand eines Beispiels lernen</h3>
<p>Das <a href="/Project:de/Beispiel_Interface" title="Project:de/Beispiel_Interface">Beispiel Interface</a> zeigt ein ausgedachtes Interface, welches ein Beispiel für eine komplette Schnittstellenreferenz darstellt. Dieser Beispielartikel kann sehr hilfreich zur Dokumentation von Schnittstellen sein.</p>
<p>Wirkliche Schnittstellen, die gut dokumentiert sind, sind zum Beispiel: <code><a href="/en/nsIFeedProcessor" title="en/nsIFeedProcessor">nsIFeedProcessor</a></code>, <code><a href="/en/nsIFeedContainer" title="en/nsIFeedContainer">nsIFeedContainer</a></code>, <code><a href="/en/nsIFeedTextConstruct" title="en/nsIFeedTextConstruct">nsIFeedTextConstruct</a></code> und <code><a href="/en/nsIScriptableUnescapeHTML" title="en/nsIScriptableUnescapeHTML">nsIScriptableUnescapeHTML</a></code>.</p>
<h3>Abschnitte in der Schnittstellenreferenz</h3>
<p>Jede Schnittstellenreferenz hat wenigsten eine Einleitung (welche keine Überschrift trägt). Die Einleitung sollte einen Überblick darüber liefern, wofür das Interface benutzt wird.</p>
<p>Nach dem Inhaltsverzeichnis wird die <code><a href="/Template:InterfaceStatus" title="Template:InterfaceStatus"><span class="nowiki">InterfaceStatus</span></a></code> Vorlage verwendet, um den Ort sowie den Status der Schnittstelle anzugeben.</p>
<p>Die Parameter der <code><span class="nowiki">{{InterfaceStatus}}</span></code> Vorlage sind:</p>
<ul> <li>Der Schnittstellenname</li> <li>Der Pfad zur IDL Datei für das Interface (z.B. <code>xpcom/ds/nsIObserver.idl</code>)</li> <li>"FROZEN" oder "unfrozen" abhängig davon, ob das Interface entweder das eine oder das andere ist.</li> <li>Die Mozilla-Version, in der das Interface zuletzt geändert wurde (zum Beispiel "Mozilla 1.8")</li> <li>"yes" wenn das Interface skriptbar ist oder "no" falls das nicht der Fall ist</li>
</ul>
<p>Schließlich sollte eine "Erbt von:" Zeile vorhanden sein, die die Elternschnittstellen auflistet. Genau so sollte eine <span class="comment">Zeile "Implementiert von:" vorhanden sein, die die Schnittstellen auflistet, die von diesem Interface abgeleitet werden</span>.</p>
<p>Alle weiteren Abschnitte sind optional und ob diese benötigt werden, variiert von Interface zu Interface. Die optionalen Abschnitte sind:</p>
<h4>Methodenüberblick</h4>
<p>Der Methodenüberblick besteht aus einer Tabelle, die einfach alle Methoden für das Interface auflistet. Der Methodenname sollte ein Link sein, welcher auf die Methode selbst verweist. Am Besten werden die Methoden alphabetisch aufgelistet.</p>
<p>Wenn eine Methode mehrere Typen für einen Eingabeparameter unterstützt, können die über das Format [type1, type2, ..., typeN] unterschieden werden.</p>
<h4>Attribute</h4>
<p>Der Abschnitt zu den Attributen besteht aus einer drei-spaltigen Tabelle. Die erste Spalte enthält den Namen jedes Attributs. Die zweite Spalte gibt den Typen jedes Attributs an (bei nicht trivialen Typen sollte ein Link zu einer erklärenden Seite gesetzt werden). Die dritte Spalte beschreibt das Attribut in dem die Verwendung und weitere Details angegeben werden. Attribute sollten in alphabetischer Reihenfolge notiert werden.</p>
<h4>Konstanten</h4>
<p>Jede Gruppe von Konstanten sollte einen Unterabschnitt besitzen, der eine Tabelle enthält, welche die relevanten Konstanten beschreibt. Die Tabelle sollte drei Spalten haben: Konstante (Namen der Konstanten), Wert (die Werte) und Beschreibung (beschreibender Text; Erklärung).</p>
<h4>Methoden</h4>
<p>Der Abschnitt zu den Methoden liefert detaillierte Dokumentation für jede Methode der Schnittstelle. Innerhalb des Methodenabschnitts sollte ein Unterbereich für jede einzelne Methode bereitgestellt werden. Jeder Methodenabschnitt sollte nach dem Methodennamen mit Klammern benannt werden (so wie "parseAsync()" in der {{ Interface("nsIFeedProcessor") }} Schnittstellenreferenz.</p>
<p>Die Methoden sollten in der selben Reihenfolge aufgeführt werden, wie sie auch im "Methodenüberblick" genannt werden.</p>
<p>Jeder Methodenabschnitt sollte wieder mit einer Beschreibung anfangen, gefolgt von der Methodensignatur selbst. Jeder Parameter sollte in einer einzelnen ZEile aufgeführt werden, sodass diese leicht zu erkennen sind.</p>
<p>Nach der Methodensignatur sollte ein Parameterabschnitt folgen. Damit das Inhaltsverzeichnis der Seite nicht unnötig lang wird, nutzen wir <code><span class="nowiki">&lt;h5&gt;Parameter&lt;/h5&gt;</span></code>, um die Überschriften der Parameter zu definieren.</p>
<p>Die Parameter werden dann mit ihren Beschreibungen in Definitionslisten aufgeführt. Wenn keine Parameter vorhanden sind, wird einfach 'Keine' unter der Parameterüberschrift geschrieben.</p>
<p>Falls eine Methode einen Rückgabewert hat, wird ein Abschnitt <code><span class="nowiki">&lt;h5&gt;Rückgabewert&lt;/h5&gt;</span></code> hinzugefügt. Dieser Teilabschnitt sollte einfach nur den Rückgabewert erklären, den Typ nennen und eventuell geläufige Rückgabewerte aufzählen.</p>
<p>Falls eine Methode Exceptions auswerfen kann, wird ein "Exceptions" Abschnitt hinzugefügt, welcher eine Definitionsliste mit möglichen Exceptions enthält.</p>
<p>Ein gutes Beispiel, welches all diese Teilabschnitte enthält, siehe {{ Interface-method("nsIScriptableUnescapeHTML", "parseFragment") }}.</p>
<h4>Bemerkungen</h4>
<p>Etwaige Kommentare zur Schnittstelle als Ganzes können unter "Bemerkungen" aufgeführt werden.</p>
<h4>Siehe auch</h4>
<p>Hilfreiche Links zu anderen Schnittstellen oder Dokumenten sollten in einem "Siehe auch" Abschnitt notiert werden.</p>
<h3>Artikel kategorisieren</h3>
<p>Jeder Artikel, der ein Interface dokumentiert muss mit dem Tag "Interfaces" versehen werden. Weitere passende Tags sollten außerdem gesetzt werden.</p>
<h3>Weitere hilfreiche Vorlagen</h3>
<p>Verwenden Sie <a href="/Project:de/Spezielle_Vorlagen" title="Project:de/Spezielle_Vorlagen">MDC: Spezielle Vorlagen</a> wenn passend, speziell <a href="/Template:interface" title="Template:interface">Template:interface</a>, wenn Sie auf andere Schnittstellen verlinken und <a href="/Template:interface-method" title="Template:interface-method">Template:interface-method</a> wenn Sie auf eine bestimmte Methode einer Schnittstelle verlinken.</p>
<h3>Artikel finden, die noch verbessert werden können</h3>
<p>Schauen Sie durch <a href="/Special:Tags?tag=Interfaces&amp;language=en" title="Special:Tags?tag=Interfaces&amp;language=en">die Liste der Schnittstellen</a> und überprüfen Sie, ob welche in der Kategorie <a href="/Special:Tags?tag=NeedsMarkupWork&amp;language=en" title="Special:Tags?tag=NeedsMarkupWork&amp;language=en">NeedsMarkupWork</a> markiert wurden. Das sind Schnittstellen von denen wir wissen, das sie noch durch dieses Layout formatiert werden müssen. Wenn Sie eines verbessert haben, entfernen Sie den Tag entsprechend.</p>
{{ languages( { "en": "Project:en/Writing_interface_reference_documentation" } ) }}
Zu dieser Version zurücksetzen