Sections de syntaxe

Syntaxe de référence d'API

Les sections de syntaxe pour les pages de référence d'API sont rédigées manuellement et peuvent varier légèrement selon la fonctionnalité documentée. La section commence par un titre (généralement un titre de niveau deux ##) nommé « Syntaxe », et doit être placée en haut de la page de référence (juste sous l'introduction). Sous le titre se trouve un bloc de code affichant la syntaxe exacte de la fonctionnalité, délimité par des backticks de code fence ```[langage-markup].

L'exemple ci-dessous montre le code Markdown pour une section Syntaxe typique (pour une fonction JavaScript) :

## Syntaxe

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

Règles générales de style

Quelques règles à suivre pour le balisage dans le bloc de syntaxe :

• Ne pas terminer une ligne par un point-virgule ;. Les sections de syntaxe ne sont pas destinées à montrer du code exécutable. Il n'est donc pas pertinent d'afficher des points-virgules.

• Ne pas utiliser <code> dans le bloc de syntaxe (ni dans aucun bloc d'exemple de code sur MDN). Non seulement c'est inutile, mais notre balisage ne le veut pas et il ne s'affichera pas comme vous le souhaitez.

• Spécifiez uniquement la fonction et ses arguments. Exemples « corrigés » ci-dessous :

  js

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

Constructeurs et méthodes

Bloc de syntaxe

Commencez par un bloc de syntaxe, comme ceci (depuis la page du constructeur IntersectionObserver()) :

new IntersectionObserver(callback, options)

ou ceci (depuis Document.hasStorageAccess()) :

hasStorageAccess()

Quand la méthode est statique, par exemple URL.createObjectURL(), indiquez aussi son interface :

URL.createObjectURL(object)

Plusieurs lignes/Paramètres optionnels

Les méthodes pouvant être utilisées de plusieurs façons doivent être détaillées sur plusieurs lignes, montrant toutes les variantes possibles.

Chaque option doit être sur sa propre ligne, sans commentaire ni affectation par option. Par exemple, Array.prototype.slice() a deux paramètres optionnels, et serait documentée ainsi :

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

De même pour CanvasRenderingContext2D.drawImage :

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

De même pour le constructeur Date :

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)

Syntaxe formelle

La notation de syntaxe formelle (utilisant la BNF) ne doit pas être utilisée dans la section Syntaxe — utilisez plutôt le format multi-lignes détaillé ci-dessus.

Bien que la notation formelle soit concise pour décrire des syntaxes complexes, elle n'est pas familière à beaucoup de développeur·euse·s et peut entrer en conflit avec la syntaxe valide de certains langages. Par exemple, [ ] indique à la fois un « paramètre optionnel » et un Array JavaScript. On le voit dans la syntaxe formelle de Array.prototype.slice() ci-dessous :

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

Dans certains cas particuliers, une section Syntaxe formelle séparée peut être ajoutée.

Blocs de syntaxe concis

L'objectif est de rendre le bloc de syntaxe aussi pur et non ambigu que possible — n'incluez aucune syntaxe inutile. Par exemple, on voit souvent ce type de syntaxe pour décrire les promesses :

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

Mais cette version est bien plus concise et n'inclut pas l'appel superflu à Promise.prototype.then() :

match(request, options)

Blocs de syntaxe pour callbacks

Pour les méthodes acceptant une fonction de rappel, indiquez le callback comme paramètre, pas comme fonction fléchée ni expression function.

filter(callbackFn)
filter(callbackFn, thisArg)

Ensuite, dans la section « Paramètres », listez les paramètres du callback et ce qu'il doit retourner.

- `callbackFn`
  - : Fonction exécutée pour chaque élément du tableau. Elle doit retourner une valeur [vraie](/fr/docs/Glossary/Truthy) pour conserver l'élément dans le tableau résultant, et une valeur [fausse](/fr/docs/Glossary/Falsy) sinon. La fonction est appelée avec les arguments suivants :
    - `element`
      - : Élément courant traité dans le tableau.
    - `index`
      - : Index de l'élément courant traité dans le tableau.
    - `array`
      - : Tableau sur lequel `filter()` a été appelé.

Syntaxe pour un nombre arbitraire de paramètres

Pour les méthodes acceptant un nombre arbitraire de paramètres, le bloc de syntaxe s'écrit ainsi :

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

Privilégiez une numérotation à partir de 1, ce qui permet d'écrire des descriptions comme « unshift ajoute N éléments au début du tableau », ou « le premier élément » (plutôt que « l'élément zéro »).

Notez que le cas où aucun paramètre n'est passé est toujours inclus, même si cela n'a pas beaucoup de sens. Ensuite, dans la section « Paramètres », écrivez :

- `element1`, …, `elementN`
  - : Les éléments à ajouter au début du tableau.

Ajoutez {{Optional_Inline}} ici si le passage de zéro paramètre est pertinent.

Autre exemple avec des paramètres positionnels avant le reste :

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

Section paramètres

Ajoutez ensuite une sous-section « Paramètres », qui explique chaque paramètre dans une liste de description. Les paramètres objets peuvent inclure une liste de description imbriquée détaillant chaque membre. Les paramètres optionnels doivent être marqués avec la macro {{Optional_Inline}} à côté de leur nom.

Le nom de chaque paramètre doit être entouré de backticks markdown ` `.

Section valeur de retour

Ajoutez ensuite une sous-section « Valeur de retour », qui explique ce que retourne le constructeur ou la méthode. Voir les liens ci-dessus pour des exemples.

S'il n'y a pas de valeur de retour, utilisez :

Aucune ({{JSxRef("undefined")}}).

Section exceptions

Enfin, ajoutez une sous-section « Exceptions », qui explique quelles exceptions peuvent être levées si un problème survient lors de l'appel du constructeur/méthode. Cela peut être dû à une faute de frappe dans un nom de paramètre, à une valeur de mauvais type, à un problème d'environnement (par exemple, tentative d'utilisation d'une fonctionnalité réservée au contexte sécurisé dans un contexte non sécurisé), ou autre.

Pour déterminer les exceptions levées par une méthode, il faut souvent consulter la spécification. L'analyse des étapes détaillées de la spec permet généralement d'obtenir la liste des exceptions et des situations qui les déclenchent.

Les noms et explications des exceptions doivent être inclus dans une liste de description.

Propriétés

Section valeur

Les propriétés n'ont pas de section de syntaxe. Ajoutez plutôt une section « Valeur » expliquant la valeur de la propriété, son type de donnée et son usage.

Section exceptions

Si l'accès à la propriété peut lever une exception, ajoutez une sous-section « Exceptions » détaillant chaque exception, comme pour les méthodes et constructeurs.

Syntaxe de référence JavaScript

Les pages de référence des objets natifs JavaScript suivent les mêmes règles de base que les pages de référence d'API (pour les méthodes et propriétés). Quelques différences peuvent être observées :

• Pour les objets natifs avec un seul constructeur, la syntaxe du constructeur est souvent incluse sur la page d'accueil de l'objet. Voir Date par exemple. Les méthodes statiques (celles qui existent sur l'objet Date lui-même) sont listées sous « Méthodes », tandis que les méthodes d'instance sont sous « Méthodes de Date.prototype  ».
• Les méthodes sans paramètres ou exceptions ont plus souvent ces sous-sections omises sur les pages de référence JavaScript. Voir Date.getDate() et Date.now() par exemple.

Syntaxe de référence CSS

Propriétés

Les pages de référence des propriétés CSS incluent une section « Syntaxe », autrefois placée en haut de la page mais de plus en plus souvent sous une section montrant un exemple d'utilisation typique et un exemple interactif (voir animation par exemple).

Dans la section syntaxe, on trouve les éléments suivants.

Texte d'explication optionnel

Certaines propriétés CSS sont évidentes et n'ont pas besoin d'explication supplémentaire (par exemple color). D'autres sont plus complexes et nécessitent des explications sur l'ordre des valeurs, la multiplicité, etc. (voir animation). Dans ces cas, ajoutez une explication avant les sous-sections.

Section valeurs

Ajoutez ensuite une section « Valeurs » — elle contient une liste de description expliquant les types de valeurs CSS qui composent la valeur de la propriété. Chaque type doit être entouré de chevrons et lié à la page de référence MDN correspondante si elle existe. Par exemple, voir la propriété border — elle référence trois types de valeurs, dont un seul est lié (<color>).

Syntaxe formelle

La dernière section, « Syntaxe formelle », est générée automatiquement avec la macro {{CSSSyntax}}. Cette macro récupère les données des spécifications CSS via le package @webref/css npm ^(angl.). Pour inclure la syntaxe formelle :

1. Ajoutez un titre : ## Syntaxe formelle.
2. Placez la macro {{CSSSyntax}} juste en dessous.

Sélecteurs

La section « Syntaxe » des pages de référence de sélecteurs est bien plus simple que celle des propriétés. Elle contient un bloc unique au style « Syntax Box », qui montre la syntaxe de base du sélecteur, qu'il s'agisse d'un simple mot-clé (par exemple :hover), ou d'une fonction complexe prenant un paramètre (par exemple :not()). Parfois, le paramètre est expliqué dans une entrée supplémentaire dans le bloc (voir :nth-last-of-type()).

Ce bloc est généré automatiquement à partir des données du dossier CSS du dépôt de données MDN ^(angl.). Il suffit d'inclure la macro CSSSyntax sous le titre, elle s'occupe du reste.

La seule difficulté est de s'assurer que les données nécessaires sont présentes. Le fichier selectors.json ^(angl.) doit contenir une entrée pour le sélecteur documenté.

Pour cela, forkez le dépôt de données MDN ^(angl.), clonez votre fork, faites les modifications dans une nouvelle branche, puis soumettez une pull request. Plus de détails sur Git ici.

Syntaxe de référence HTML

Les pages de référence HTML n'ont pas de section « Syntaxe » — la syntaxe est toujours le nom de l'élément entouré de chevrons, donc ce n'est pas nécessaire. L'essentiel à savoir est quels attributs l'élément accepte et leurs valeurs, ce qui est couvert dans une section « Attributs ». Voir <ol> et <video> par exemple.

Syntaxe de référence HTTP

La syntaxe de référence HTTP est entièrement rédigée à la main et varie selon le type de fonctionnalité HTTP documentée.

En-têtes HTTP/Content-Security-Policy

La syntaxe des en-têtes HTTP (et Content-Security-Policy) est documentée dans deux sections distinctes — « Syntaxe » et « Directives ».

Section syntaxe

La section « Syntaxe » montre à quoi ressemble la syntaxe d'un en-tête, avec un bloc de syntaxe au style « Syntax Box », incluant la syntaxe formelle pour montrer exactement quelles directives peuvent être incluses, dans quel ordre, etc. Par exemple, le bloc de syntaxe de l'en-tête If-None-Match ressemble à :

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

Certains en-têtes ont des syntaxes séparées pour les directives de requête, de réponse et d'extension. Si c'est le cas, incluez-les dans des blocs distincts, chacun sous sa propre sous-section. Voir Cache-Control par exemple.

Section directives

La section « Directives » contient une liste de description avec les noms et descriptions de toutes les directives possibles dans la syntaxe.

Méthodes de requête HTTP

La syntaxe des méthodes de requête est très simple : un bloc de syntaxe au style « Syntax Box » montrant la structure de la méthode. La syntaxe de la méthode GET ressemble à :

GET /index.html

Codes de statut de réponse HTTP

Là encore, la syntaxe des codes de statut HTTP est très simple : un bloc de syntaxe avec le code et le nom. Exemple :

404 Not Found

Syntaxe de référence SVG

Éléments SVG

Les sections de syntaxe des éléments SVG n'existent pas — comme pour les éléments HTML. Chaque page de référence d'élément SVG inclut simplement la liste des attributs applicables. Voir <feTile> par exemple.

Attributs SVG

Les pages de référence d'attributs SVG n'incluent pas non plus de section de syntaxe.

Voir aussi

• Markdown sur MDN