Syntax-Abschnitte

Syntaxabschnitte für API-Referenzseiten werden manuell geschrieben und können je nach dokumentiertem Feature leicht variieren. Der Abschnitt beginnt mit einer Überschrift (typischerweise eine Überschrift der Ebene zwei ##) mit dem Namen "Syntax" und muss am Anfang der Referenzseite enthalten sein (direkt unter dem einleitenden Material). Unter der Überschrift befindet sich ein Codeblock, der die genaue Syntax des Features zeigt, abgetrennt durch einen Codezaun ```[Markup-Sprache] Klasse.

Das folgende Beispiel zeigt den Markdown-Code für einen typischen Syntaxabschnitt (für eine JavaScript-Funktion):

## Syntax

```js-nolint
slice()
slice(start)
slice(start, end)
```

Einige Regeln, die bezüglich der Auszeichnung innerhalb des Syntaxblocks zu beachten sind:

• Beenden Sie eine Zeile nicht mit einem Semikolon ;. Syntaxabschnitte sind nicht dazu gedacht, ausführbaren Code zu zeigen. Daher macht es keinen Sinn, Semikolons zu zeigen.

• Verwenden Sie kein <code> innerhalb des Syntaxblocks (oder in einem beliebigen Codebeispielblock auf MDN). Nicht nur ist es im Allgemeinen nutzlos, auch unsere Auszeichnung möchte es nicht, und es wird nicht so gerendert, wie Sie es sich wünschen, wenn Sie es einfügen.

• Geben Sie nur die Funktion und Argumente an. Beispiel einer "korrigierten" Beispiele unten

  js

  querySelector(selector)
  // responseStr = element.querySelector(selector)
  
  new IntersectionObserver(callback, options)
  // const observer = new IntersectionObserver(callback, options)
  

Syntaxblock

Beginnen Sie mit einem Syntaxblock wie diesem (von der IntersectionObserver() Konstruktorseite):

new IntersectionObserver(callback, options)

oder diesem (von Document.hasStorageAccess()):

hasStorageAccess()

Wenn die Methode statisch ist, zum Beispiel URL.createObjectURL(), geben Sie auch ihre Schnittstelle an:

URL.createObjectURL(object)

Mehrere Zeilen/Optionale Parameter

Methoden, die auf viele verschiedene Arten verwendet werden können, sollten in mehrere Zeilen aufgeschlüsselt werden, die alle möglichen Variationen zeigen.

Jede Option sollte in einer eigenen Zeile stehen, wobei sowohl pro-Option-Kommentare als auch Zuweisungen weggelassen werden. Zum Beispiel hat Array.prototype.slice() zwei optionale Parameter und würde wie unten gezeigt dokumentiert werden:

slice()
slice(begin)
slice(begin, end)

Ähnlich für CanvasRenderingContext2D.drawImage:

drawImage(image, dx, dy)
drawImage(image, dx, dy, dWidth, dHeight)
drawImage(image, sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight)

Ebenso beim Date Konstruktor:

new Date()
new Date(value)
new Date(dateString)
new Date(year, monthIndex)
new Date(year, monthIndex, day)
new Date(year, monthIndex, day, hours)
new Date(year, monthIndex, day, hours, minutes)
new Date(year, monthIndex, day, hours, minutes, seconds, milliseconds)

Formale Syntax

Formale Syntaxnotation (unter Verwendung von BNF) sollte nicht im Syntaxabschnitt verwendet werden – stattdessen verwenden Sie das erweiterte mehrzeilige Format oben beschrieben.

Während die formale Notation einen prägnanten Mechanismus zur Beschreibung komplexer Syntax bietet, ist sie vielen Entwicklern nicht vertraut und kann mit der gültigen Syntax bestimmter Programmiersprachen kollidieren. Beispielsweise bedeutet [ ] sowohl einen "optional Parameter" als auch ein JavaScript Array. Sie können dies in der formalen Syntax für Array.prototype.slice() unten sehen:

arr.slice([begin[, end]])

Für spezifische Fälle, in denen es als vorteilhaft angesehen wird, kann ein separater Formale Syntax Abschnitt unter Verwendung der formalen Benachrichtigung deklariert werden.

Knapp gehaltene Syntaxblöcke

Ziel ist es, den Syntaxblock so rein und eindeutig wie möglich als Definition der Syntax des Features zu machen – schließen Sie keine irrelevante Syntax ein. Beispielsweise können Sie diese Syntaxform, die an vielen Stellen auf der Seite verwendet wird, sehen, um Versprechen zu beschreiben:

caches.match(request, options).then(function (response) {
  // Do something with the response
})

Aber diese Version ist viel prägnanter und enthält nicht den überflüssigen Promise.prototype.then() Methodenaufruf:

match(request, options)

Rückruf-Syntaxblöcke

Für Methoden, die eine Rückruffunktion akzeptieren, zeigen Sie den Rückruf als Parameter und nicht als Pfeilfunktion oder function Ausdruck an.

filter(callbackFn)
filter(callbackFn, thisArg)

Dann, im Abschnitt "Parameter", listen Sie die Parameter der Rückruffunktion auf und was sie zurückgeben soll.

- `callbackFn`
  - : A function to execute for each element in the array. It should return a [truthy](/en-US/docs/Glossary/Truthy) value to keep the element in the resulting array, and a [falsy](/en-US/docs/Glossary/Falsy) value otherwise. The function is called with the following arguments:
    - `element`
      - : The current element being processed in the array.
    - `index`
      - : The index of the current element being processed in the array.
    - `array`
      - : The array `filter()` was called upon.

Syntax für eine beliebige Anzahl von Parametern

Für Methoden, die eine beliebige Anzahl von Parametern akzeptieren, wird der Syntaxblock wie folgt geschrieben:

unshift()
unshift(element1)
unshift(element1, element2)
unshift(element1, element2, /* …, */ elementN)

Bevorzugen Sie, die Nummerierung bei 1 beginnen zu lassen, was es ermöglicht, die Beschreibung wie "unshift fügt N Elemente an den Anfang des Arrays hinzu" sowie "das erste Element" (statt "das nullte Element") zu schreiben.

Beachten Sie, dass der Fall, keine Restparameter zu übergeben, immer enthalten ist, auch wenn es nicht viel Sinn macht. Dann schreiben Sie im Abschnitt "Parameter" Folgendes:

- `element1`, …, `elementN`
  - : The elements to add to the front of the array.

Fügen Sie hier {{optional_inline}} hinzu, wenn das Übergeben von null Restparameter Sinn hat.

Ein weiteres Beispiel mit einigen Positionsparametern vor dem Restparameter:

splice(start)
splice(start, deleteCount)
splice(start, deleteCount, item1)
splice(start, deleteCount, item1, item2)
splice(start, deleteCount, item1, item2, /* …, */ itemN)

Parameterabschnitt

Fügen Sie als nächstes einen "Parameter"-Unterabschnitt hinzu, der erklärt, was jeder Parameter in einer Beschreibungsliste sein soll. Parameter, die Objekte mit mehreren Mitgliedern sind, können eine verschachtelte Beschreibungsliste enthalten, die ihrerseits eine Erklärung dazu enthält, was jedes Mitglied sein soll. Optionale Parameter sollten mit einem {{optional_inline}} Makroaufruf neben ihrem Namen im Beschreibungsterm markiert werden.

Der Name jedes Parameters in der Liste sollte in Markdown-Codezaunnotation ` ` enthalten sein.

Rückgabewertabschnitt

Fügen Sie als nächstes einen "Rückgabewert"-Unterabschnitt hinzu, der erklärt, was der Rückgabewert des Konstruktors oder der Methode ist. Siehe die obigen Links als Beispiele.

Wenn es keinen Rückgabewert gibt, verwenden Sie den folgenden Text:

Keiner ({{jsxref("undefined")}}).

Ausnahmenabschnitt

Fügen Sie schließlich einen "Ausnahmen"-Unterabschnitt hinzu, der erklärt, welche Ausnahmen auftreten können, wenn ein Problem beim Aufrufen des Konstruktors/der Methode auftritt. Dies könnte daran liegen, dass ein Parametername falsch geschrieben wurde oder ihm ein falscher Datentyp-Wert gegeben wurde, weil es ein Problem mit der Umgebung gibt, in der es aufgerufen wird (z.B. wenn versucht wird, ein nur für sichere Kontexte geeignetes Feature in einem nicht sicheren Kontext auszuführen), oder aus einem anderen Grund.

Zu bestimmen, welche Ausnahmen von einer Methode ausgelöst werden, kann eine gründliche Untersuchung der Spezifikation erfordern. Das Durchsehen der schrittweisen Erklärung in der Spezifikation, wie ein Feature funktioniert, liefert normalerweise eine solide Liste von Ausnahmen und Situationen, die zu deren Auslösung führen.

Die Namen und Erklärungen der Ausnahmen sollten in einer Beschreibungsliste enthalten sein.

Wertabschnitt

Eigenschaften enthalten keinen Syntaxabschnitt. Stattdessen fügen Sie einen "Wert"-Abschnitt hinzu, der eine Erklärung des Wertebereichs der Eigenschaft enthält. Beschreiben Sie den Datentyp und den Zweck.

Ausnahmenabschnitt

Wenn beim Zugriff auf die Eigenschaft eine Ausnahme ausgelöst werden kann, fügen Sie einen "Ausnahmen"-Unterabschnitt hinzu, der jede Ausnahme erklärt; dieser sollte genauso eingerichtet sein wie der oben für Methoden und Konstruktoren beschriebene.

JavaScript-Referenzseiten für eingebaute Objekte folgen den gleichen grundlegenden Regeln wie API-Referenzseiten; z.B. für Methoden und Eigenschaften. Es gibt einige Unterschiede, die Sie möglicherweise beobachten:

• Für eingebaute Objekte mit einem einzelnen Konstruktor wird die Konstruktorsyntax häufig auf der Objekt-Landingpage eingeschlossen. Siehe Date zum Beispiel. Sie werden feststellen, dass statische Methoden (die auf dem Date-Objekt selbst existieren) unter "Methoden" aufgeführt sind, während Instanzmethoden unter "Date.prototype Methoden" aufgelistet sind.
• Sie werden auch feststellen, dass bei Methoden, die keine Parameter/Ausnahmen haben, diese Unterabschnitte auf JavaScript-Referenzseiten eher überhaupt nicht enthalten sind. Siehe Date.getDate() und Date.now() für Beispiele.

CSS-Referenzseiten für Eigenschaften enthalten einen "Syntax"-Abschnitt, der früher oben auf der Seite gefunden wurde, aber zunehmend häufig unter einem Abschnitt zu finden ist, der einen Codeblock zeigt, der die typische Verwendung des Features zeigt, plus ein Live-Beispiel, um zu veranschaulichen, was das Feature macht (siehe animation als Beispiel).

Im Syntaxabschnitt finden Sie folgende Inhalte.

Optionaler Erklärungstext

Einige CSS-Eigenschaften erklären sich von selbst und benötigen keine zusätzliche Erklärung (zum Beispiel color). Einige hingegen sind komplexer und brauchen Erklärungen zur Syntaxreihenfolge, einschließlich mehrerer Werte usw. (siehe animation). In solchen Fällen können Sie vor den Unterabschnitten zusätzliche Erklärungen einfügen.

Werteabschnitt

Als nächstes sollten Sie einen "Werte"-Abschnitt einfügen – dieser enthält eine Beschreibungsliste, die die CSS-Wertetypen erklärt, die den Wert der Eigenschaft bilden. Jeder Wertetyp sollte in spitzen Klammern eingefasst und auf die MDN-Referenzseite zu diesem Wertetyp verlinkt werden, wenn eine Seite dafür existiert. Beispielsweise siehe die border-Eigenschaftsreferenz – diese referenziert drei Wertetypen, von denen nur einer verlinkt ist (<color>).

Formale Syntax

Der letzte Abschnitt, "Formale Syntax", wird automatisch aus den im MDN data repo enthaltenen Daten im CSS-Verzeichnis generiert. Sie müssen nur einen CSSSyntax-Makroaufruf unter der Überschrift einfügen, und es wird den Rest erledigen.

Die einzige Komplikation ergibt sich daraus, sicherzustellen, dass die benötigten Daten vorhanden sind. Die properties.json-Datei muss einen Eintrag für die dokumentierte Eigenschaft enthalten, und die types.json-Datei muss einen Eintrag für alle Wertetypen enthalten, die im Wert der Eigenschaft verwendet werden.

Sie müssen dies tun, indem Sie das MDN data repo forken, Ihren Fork lokal klonen, die Änderungen in einem neuen Branch vornehmen und dann einen Pull Request gegen das Upstream-Repo einreichen. Sie können hier mehr Details zur Verwendung von Git finden.

Der "Syntax"-Abschnitt von Selektor-Referenzseiten ist viel einfacher als der von Eigenschaftsseiten. Er enthält einen Block, der im "Syntax Box"-Stil gestaltet ist und die grundlegende Syntax des Selektors zeigt, sei es nur ein einfaches Schlüsselwort (z.B. :hover), oder ein komplexerer Funktionswert, der einen Parameter akzeptiert (z.B. :not()). Manchmal wird der Parameter in einem weiteren Eintrag innerhalb des Syntaxblocks erklärt (siehe :nth-last-of-type() als Beispiel).

Dieser Block wird automatisch aus den Daten im MDN data repo's CSS-Verzeichnis generiert. Sie müssen nur einen CSSSyntax-Makroaufruf unter der Überschrift einfügen, und es wird den Rest erledigen.

Die einzige Komplikation ergibt sich daraus, sicherzustellen, dass die benötigten Daten vorhanden sind. Die selectors.json-Datei muss einen Eintrag für den dokumentierten Selektor enthalten.

Sie müssen dies tun, indem Sie das MDN data repo forken, Ihren Fork lokal klonen, die Änderungen in einem neuen Branch vornehmen und dann einen Pull Request gegen das Upstream-Repo einreichen. Sie können hier mehr Details zur Verwendung von Git finden.

HTML-Referenzseiten haben keine "Syntax"-Abschnitte – die Syntax besteht immer nur aus dem Elementnamen, der in spitze Klammern eingeschlossen ist, daher ist es nicht nötig. Das Hauptsächliche, das man über HTML-Elemente wissen muss, ist, welche Attribute sie annehmen und welche Werte sie annehmen können, und dies wird in einem separaten "Attribute"-Abschnitt behandelt. Siehe <ol> und <video> als Beispiele.

Die HTTP-Referenzsyntax wird vollständig manuell erstellt und variiert je nachdem, welcher HTTP-Featuretyp dokumentiert wird.

Die Syntax von HTTP-Headern (und Content-Security-Policy) wird in zwei separaten Abschnitten auf der Seite dokumentiert – "Syntax" und "Direktiven".

Syntaxabschnitt

Der "Syntax"-Abschnitt zeigt, wie die Syntax eines Headers aussieht, unter Verwendung eines Syntaxblocks, der im "Syntax Box"-Stil gestaltet ist, inklusive formaler Syntax, um genau zu zeigen, welche Direktiven im Wert enthalten sein können, in welcher Reihenfolge usw. Zum Beispiel sieht der Syntaxblock des If-None-Match Headers so aus:

If-None-Match: <etag_value>
If-None-Match: <etag_value>, <etag_value>, …
If-None-Match: *

Einige Header haben separate Anforderungsdirektiven-, Antwortdirektiven- und Erweiterungssyntax. Falls verfügbar, müssen diese in separaten Syntaxblöcken enthalten sein, jeweils unter ihrem eigenen Unterabschnitt. Siehe Cache-Control als Beispiel.

Direktivenabschnitt

Der "Direktiven"-Abschnitt enthält eine Beschreibungsliste mit den Namen und Beschreibungen aller Direktiven, die innerhalb der Syntax erscheinen können.

Die Syntax der Anfragemethode ist sehr einfach und enthält nur einen Syntaxblock, der im "Syntax Box"-Stil gestaltet ist und zeigt, wie die Syntax der Methode strukturiert ist. Die Syntax für die GET-Methode sieht so aus:

GET /index.html

Ebenso ist die Syntax für HTTP-Antwortstatuscodes sehr einfach – ein Syntaxblock einschließlich des Codes und Namens. Zum Beispiel:

404 Not Found

Syntaxabschnitte für SVG-Elemente existieren nicht – ebenso wie HTML-Element-Syntaxabschnitte. Jede SVG-Element-Referenzseite enthält nur eine Liste der Attribute, die auf das betreffende Element angewendet werden können. Siehe <feTile> als Beispiel.

SVG-Attribut-Referenzseiten enthalten auch keine Syntaxabschnitte.

• Markdown in MDN