Syntaxabschnitte

Syntaxabschnitte für API-Referenzseiten werden manuell erstellt und können je nach dokumentiertem Feature leicht variieren. Der Abschnitt beginnt mit einer Überschrift (typischerweise eine Überschrift der Stufe zwei ##) mit dem Namen "Syntax" und muss oben auf der Referenzseite (direkt unter dem einführenden Material) enthalten sein. Unter der Überschrift befindet sich ein Codeblock, der die genaue Syntax des Features zeigt, abgegrenzt durch den 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 im Hinblick auf die Markup innerhalb des Syntaxblocks befolgt werden sollten:

• Beenden Sie eine Zeile nicht mit einem Semikolon ;. Syntaxabschnitte sollen keinen ausführbaren Code zeigen. Es macht also keinen Sinn, Semikolons zu zeigen.

• Verwenden Sie nicht <code> innerhalb des Syntaxblocks (oder in einem beliebigen Codebeispiel-Block auf MDN). Es ist nicht nur im Allgemeinen nutzlos, sondern unser Markup möchte es nicht, und es wird nicht so gerendert, wie Sie möchten, wenn Sie es einfügen.

• Geben Sie nur die Funktion und die Argumente an. Beispiel, das unten "korrigierte" Beispiele zeigt:

  jsCopy to Clipboard

  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, z. B. 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 auf mehrere Zeilen aufgeteilt werden, um alle möglichen Variationen zu 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 ist es für CanvasRenderingContext2D.drawImage:

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

Ähnlich für den 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 im Syntaxabschnitt nicht verwendet werden — stattdessen verwenden Sie das erweiterte Mehrzeilenformat oben beschrieben.

Obwohl die formelle Notation einen prägnanten Mechanismus zur Beschreibung komplexer Syntax bietet, ist sie vielen Entwicklern nicht vertraut und kann mit der gültigen Syntax für bestimmte Programmiersprachen in Konflikt geraten. Zum Beispiel zeigt [ ] sowohl einen "optionalen Parameter" als auch eine JavaScript Array an. 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 mit der formellen Benachrichtigung deklariert werden.

Prägnante Syntaxblöcke

Das Ziel ist es, den Syntaxblock so rein und eindeutig wie möglich als Definition der Syntax des Features zu machen — fügen Sie keine irrelevante Syntax hinzu. Zum Beispiel könnte diese Syntaxform verwendet werden, um Versprechungen an vielen Stellen auf der Website 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.

filter(callbackFn)
filter(callbackFn, thisArg)

Dann listen Sie im Abschnitt "Parameter" 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 so geschrieben:

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

Beginnen Sie vorzugsweise mit der Zählung ab 1, was es ermöglicht, Beschreibungen wie "unshift fügt N-Elemente am Anfang des Arrays hinzu" sowie "das erste Element" (anstatt "das nullte Element") zu schreiben.

Beachten Sie, dass der Fall, keine Restparameter zu übergeben, immer enthalten ist, auch wenn er wenig Sinn ergibt. Schreiben Sie dann im Abschnitt "Parameter" dies:

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

Fügen Sie {{optional_inline}} hier hinzu, wenn es sinnvoll ist, keinen Restparameter zu übergeben.

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)

Parameters Abschnitt

Fügen Sie anschließend einen "Parameters"-Unterabschnitt hinzu, in dem erläutert wird, was jeder Parameter sein sollte, in einer Beschreiungs- liste. Parameter, die Objekte mit mehreren Mitgliedern sind, können eine verschachtelte Beschreibungs- liste enthalten, die wiederum eine Erklärung enthält, was jedes Mitglied sein sollte. Optionale Parameter sollten mit einem {{optional_inline}} Makroaufruf neben ihrem Namen im Beschreibungsterm gekennzeichnet werden.

Der Name jedes Parameters in der Liste sollte in Markdown-Code-Zaunnotation ` ` eingeschlossen sein.

Rückgabewerte Abschnitt

Fügen Sie anschließend einen "Return value"-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 folgenden Text:

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

Ausnahmen Abschnitt

Schließlich fügen Sie einen "Exceptions"-Unterabschnitt hinzu, der erklärt, welche Ausnahmen ausgelöst werden können, wenn ein Problem beim Aufrufen des Konstruktors/der Methode auftritt. Dies könnte sein, weil ein Parametername falsch geschrieben wurde oder ihm ein Wert des falschen Datentyps gegeben wurde, weil es ein Problem mit der Umgebung gibt, in der er aufgerufen wird (z. B. Versuch, ein nur für sicheren Kontext verfügbares Feature in einem unsicheren Kontext auszuführen), oder aus einem anderen Grund.

Festzustellen, welche Ausnahmen von einer Methode ausgelöst werden können, erfordert möglicherweise eine gründliche Durchsicht der Spezifikation. Das Durchsehen der schrittweisen Erklärung der Funktionsweise eines Features in der Spezifikation liefert in der Regel eine solide Liste der Ausnahmen und der Situationen, die zu ihrem Auslösen führen.

Die Ausnahmenamen und Erklärungen sollten in einer Beschreibungs- liste enthalten sein.

Wert Abschnitt

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

Ausnahmen Abschnitt

Wenn der Zugriff auf die Eigenschaft eine Ausnahme auslösen kann, fügen Sie einen "Exceptions"-Unterabschnitt hinzu, der jede Ausnahme erklärt; dieser sollte genau wie der oben für Methoden und Konstruktoren beschriebene eingerichtet werden.

JavaScript eingebaute Objekt-Referenzseiten befolgen die gleichen grundlegenden Regeln wie API-Referenzseiten; z. B. für Methoden und Eigenschaften. Es gibt ein paar Unterschiede, die Sie beobachten könnten:

• Für eingebettete Objekte mit einem einzigen Konstruktor wird die Konstruktorsyntax oft auf der Objekt-Landingpage aufgenommen. Siehe Date als Beispiel. Sie werden feststellen, dass statische Methoden (diejenigen, die auf dem Date-Objekt selbst existieren) unter "Methods" aufgelistet sind, während Instanzmethoden unter "Date.prototype methods" aufgeführt sind.
• Ihnen wird auch auffallen, dass Methoden, die keine Parameter/Ausnahmen haben, diese Unterabschnitte auf JavaScript-Referenzseiten eher gar nicht enthalten haben. Siehe Date.getDate() und Date.now() als Beispiele.

CSS Eigenschaftsreferenzseiten enthalten einen "Syntax" Abschnitt, der früher am oberen Ende der Seite zu finden war, zunehmend jedoch unter einem Abschnitt mit einem Codeblock, der die typische Verwendung des Features zeigt, sowie einem Live-Beispiel, das das Feature illustriert, gefunden wird (siehe animation als Beispiel).

Im Inneren des Syntaxabschnitts finden Sie die folgenden Inhalte.

Optionale Erklärungstexte

Einige CSS-Eigenschaften sind selbsterklärend und benötigen keine zusätzliche Erklärung (zum Beispiel color). Einige hingegen sind komplexer und benötigen 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 hinzufügen.

Werte Abschnitt

Als Nächstes sollten Sie einen "Values" Abschnitt einschließen — dieser enthält eine Beschreibungs- liste, in der die CSS-Wertetypen erläutert werden, die den Wert der Eigenschaft ausmachen. Jeder Wertetyp sollte in spitze Klammern eingeschlossen und mit der MDN-Referenzseite verlinkt werden, die diesen Wertetyp behandelt, falls eine Seite dafür existiert. Zum Beispiel, siehe die border Eigenschaftsreferenz — diese referenziert drei Wertetypen, von denen nur einer verlinkt ist (<color>).

Formale Syntax

Der letzte Abschnitt, "Formal syntax", wird automatisch mit dem Makro {{CSSSyntax}} generiert. Dieses Makro ruft Daten aus den CSS-Spezifikationen unter Verwendung des @webref/css npm package ab. Um die formale Syntax in Ihrem Dokument einzufügen:

1. Fügen Sie eine Überschrift wie folgt hinzu: ## Formal syntax.
2. Platzieren Sie das Makro {{CSSSyntax}} direkt unterhalb dieser Überschrift.

Der "Syntax" Abschnitt von Selektorreferenzseiten ist viel einfacher als der von Eigenschaftsseiten. Er enthält einen Block, der mit dem "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 annimmt (z. B. :not()). Manchmal wird der Parameter in einem weiteren Eintrag im Syntaxblock erläutert (siehe :nth-last-of-type() als Beispiel).

Dieser Block wird automatisch aus den Daten generiert, die im CSS-Verzeichnis des MDN-Daten-Repos enthalten sind. Sie müssen lediglich einen CSSSyntax Makroaufruf unter dem Titel einfügen, und er kümmert sich um den Rest.

Die einzige Komplikation besteht darin, sicherzustellen, dass die benötigten Daten vorhanden sind. Die Datei selectors.json muss einen Eintrag für den Selektor enthalten, den Sie dokumentieren.

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

HTML-Referenzseiten haben keine "Syntax" Abschnitte — die Syntax besteht immer nur aus dem Elementnamen, eingeschlossen in spitze Klammern, also ist es nicht notwendig. Das Wichtigste, was Sie über HTML-Elemente wissen müssen, ist, welche Attribute sie annehmen können und welche Werte diese haben können, und dies ist in einem separaten "Attributes" Abschnitt behandelt. Siehe <ol> und <video> als Beispiele.

Die HTTP-Referenzsyntax wird vollständig manuell erstellt und unterscheidet sich je nach der Art des HTTP-Features, das Sie dokumentieren.

Die HTTP-Header-Syntax (und Inhalts-Sicherheitsrichtlinie) wird in zwei separaten Abschnitten auf der Seite dokumentiert — "Syntax" und "Directives".

Syntax Abschnitt

Der "Syntax" Abschnitt zeigt, wie die Syntax eines Headers aussieht, unter Verwendung eines Syntaxblocks, der mit dem "Syntax Box"-Stil gestaltet ist, inklusive formaler Syntax, die genau zeigt, 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 unterschiedliche Anforderungsdirektiven, Antwortdirektiven und Erweiterungssyntax. Wenn verfügbar, müssen diese in separaten Syntaxblöcken enthalten sein, jeweils unter ihrem eigenen Unterabschnitt. Siehe Cache-Control als Beispiel.

Richtlinien Abschnitt

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

Die Syntax für Anfragemethoden ist wirklich einfach und enthält lediglich einen Syntaxblock, der mit dem "Syntax Box"-Stil gestaltet ist und zeigt, wie die Methosyntax strukturiert ist. Die Syntax für die GET-Methode sieht folgendermaßen aus:

GET /index.html

Auch die Syntax für HTTP Antwortstatuscodes ist wirklich einfach — ein Syntaxblock, der den Code und den Namen enthält. Zum Beispiel:

404 Not Found

SVG-Element-Syntaxabschnitte existieren nicht — genau wie HTML-Element-Syntaxabschnitte. Jede SVG-Element-Referenzseite enthält lediglich eine Liste der Attribute, die auf dieses Element angewendet werden können. Siehe <feTile> als Beispiel.

Auch SVG Attribut-Referenzseiten enthalten keine Syntaxabschnitte.

• Markdown in MDN