1. MDN Web Docs
  2. Règles d'écriture
  3. Guides pratiques
  4. Rédiger une référence API

Cette page a été traduite à partir de l'anglais par la communauté. Vous pouvez contribuer en rejoignant la communauté francophone sur MDN Web Docs.

View in English Always switch to English

Comment rédiger une référence API

Ce guide vous explique tout ce que vous devez savoir pour rédiger une référence API sur MDN.

Se préparer

Avant de commencer à documenter une API, il y a certaines choses que vous devez préparer et planifier avant de commencer à écrire réellement.

Connaissances préalables

Il est supposé qu'avant de lire ce guide, vous avez une connaissance raisonnable de :

  • Les technologies Web comme HTML, CSS et JavaScript. JavaScript est le plus important.
  • La lecture des spécifications des technologies Web. Vous les consultez souvent lors de la documentation des API.

Tout le reste peut être appris en cours de route.

Ressources préalables

Avant de commencer à documenter une API, vous devez avoir à disposition :

  1. La dernière spécification : Qu'il s'agisse d'une recommandation du W3C ou d'un brouillon préliminaire, vous devez vous référer au dernier brouillon disponible de la spécification qui couvre (ou aux spécifications qui couvrent) cette API. Pour le trouver, vous pouvez généralement effectuer une recherche sur le Web. La dernière version est souvent liée à partir de toutes les versions de la spécification, listée sous « dernier brouillon » ou similaire.
  2. Les navigateurs Web modernes les plus récents : Il s'agit généralement de versions expérimentales/alpha telles que Firefox Nightly/Chrome Canary qui sont plus susceptibles de prendre en charge les fonctionnalités que vous documentez. C'est particulièrement pertinent si vous documentez une API naissante/expérimentale.
  3. Démonstrations/articles de blog/autres informations : Trouvez autant d'informations que possible.
  4. Contacts techniques utiles : Il est vraiment utile de trouver un contact technique amical pour poser des questions sur la spécification, quelqu'un qui est impliqué dans la normalisation de l'API ou son implémentation dans un navigateur. Les bons endroits pour les trouver sont :

Prenez le temps de jouer avec l'API

Vous viendrez construire des démonstrations de nombreuses fois au cours de la documentation d'une API, mais il est utile de commencer par passer du temps à se familiariser avec le fonctionnement de l'API — apprendre quelles sont les principales interfaces/propriétés/méthodes, quels sont les cas d'utilisation principaux et comment écrire des fonctionnalités simples avec elle.

Lorsque qu'une API a changé, vous devez faire attention à ce que les démonstrations existantes auxquelles vous vous référez ou que vous utilisez pour apprendre ne soient pas obsolètes. Vérifiez les principaux éléments utilisés dans la démonstration pour voir s'ils correspondent à la dernière spécification. Ils peuvent également ne pas fonctionner dans les navigateurs à jour, mais ce n'est pas un test très fiable, car souvent les anciennes fonctionnalités continuent d'être prises en charge pour la compatibilité ascendante.

Note : Si la spécification a été récemment mise à jour de sorte qu'une méthode est maintenant définie différemment, mais que l'ancienne méthode fonctionne toujours dans les navigateurs, vous devez souvent documenter les deux au même endroit, afin que les anciennes et nouvelles méthodes soient couvertes. Si vous avez besoin d'aide, référez-vous aux démonstrations que vous avez trouvées ou demandez à un contact technique.

Créez la liste des documents que vous devez rédiger ou mettre à jour

Une référence d'API contient généralement les pages suivantes. Vous pouvez trouver plus de détails sur le contenu de chaque page, des exemples et des modèles, dans notre article Types de pages. Avant de commencer, vous devez rédiger une liste de toutes les pages que vous devez créer.

  1. Page d'aperçu
  2. Pages d'interface
  3. Pages de constructeur
  4. Pages de méthode
  5. Pages de propriété
  6. Pages d'évènement
  7. Pages de concept/guide
  8. Pages d'exemples

Note : Nous nous référons à l'API Web Audio pour les exemples dans cet article.

Pages d'aperçu

Une seule page d'aperçu de l'API est utilisée pour décrire le rôle de l'API, ses interfaces de haut niveau, les fonctionnalités connexes contenues dans d'autres interfaces et d'autres détails de haut niveau. Son nom et son identifiant doivent être le nom de l'API précédé de « API ». Elle est placée au niveau supérieur de la référence de l'API, en tant qu'enfant de https://developer.mozilla.org/fr/docs/Web/API.

Exemple :

Pages d'interface

Chaque interface a également sa propre page, décrivant le but de l'interface, listant tous les membres (constructeurs, méthodes, propriétés, etc.) qu'elle contient, et montrant avec quels navigateurs elle est compatible. Le nom et l'identifiant d'une page doivent être le nom de l'interface, exactement comme écrit dans la spécification. Chaque page est placée au niveau supérieur de la référence de l'API, en tant qu'enfant de https://developer.mozilla.org/fr/docs/Web/API.

Exemples :

Note : Nous documentons chaque membre apparaissant dans l'interface. Vous devez garder à l'esprit les règles suivantes :

  • Nous documentons les méthodes définies sur le prototype d'un objet implémentant cette interface (méthodes d'instance), et les méthodes définies sur la classe elle-même (méthodes statiques). Dans les rares occasions où elles existent toutes les deux sur la même interface, vous devez les lister dans des sections séparées sur la page (Méthodes statiques/Méthodes d'instance). En général, seules les méthodes d'instance existent, auquel cas vous pouvez les mettre sous le titre « Méthodes ».
  • Nous ne documentons pas les propriétés et méthodes héritées de l'interface : elles sont listées sur l'interface parente respective. Nous faisons cependant allusion à leur existence.
  • Nous documentons les propriétés et méthodes définies dans les compositions. Veuillez consulter le guide de contribution pour les compositions pour plus de détails.
  • Les méthodes spéciales comme la mise en chaîne de caractères (toString()) et la conversion en JSON (toJSON()) sont également listées si elles existent.
  • Les constructeurs nommés (comme Image() pour HTMLImageElement) sont également listés, si pertinent.

Pages de constructeur

Chaque interface a zéro ou un constructeur, documenté sur une sous-page de la page de l'interface. Elle décrit le but du constructeur et montre à quoi ressemble sa syntaxe, des exemples d'utilisation, des informations sur la compatibilité des navigateurs, etc. Son identifiant est le nom du constructeur, qui est exactement le même que le nom de l'interface, et le titre est le nom de l'interface, point, nom du constructeur, puis parenthèses à la fin.

Exemple :

Pages de propriété

Chaque interface a zéro ou plusieurs propriétés, documentées sur des sous-pages de la page de l'interface. Chaque page décrit le but de la propriété et montre à quoi ressemble sa syntaxe, des exemples d'utilisation, des informations sur la compatibilité des navigateurs, etc. Son identifiant est le nom de la propriété, et le titre est le nom de l'interface, point, puis le nom de la propriété.

Exemples :

Pages de méthode

Chaque interface a zéro ou plusieurs méthodes, documentées sur des sous-pages de la page de l'interface. Chaque page décrit le but de la méthode et montre à quoi ressemble sa syntaxe, des exemples d'utilisation, des informations sur la compatibilité des navigateurs, etc. Son identifiant est le nom de la méthode, et le titre est le nom de l'interface, point, nom de la méthode, puis parenthèses.

Exemples :

Pages d'évènements

Documentez les évènements en tant que sous-pages de leurs interfaces cibles et utilisez le slug eventname_event avec le titre défini sur Interface: eventName event.

Ne créez pas de pages pour les propriétés de gestionnaire d'évènements on. Mentionnez les deux façons d'accéder à l'évènement sur la page eventName_event.

Exemple :

Pages de concepts/guides

La plupart des références d'API ont au moins un guide et parfois aussi une page de concepts pour les accompagner. Au minimum, une référence d'API doit contenir un guide intitulé « Utiliser nom-de-lapi », qui fournit un guide de base sur la façon d'utiliser l'API. Les API plus complexes peuvent nécessiter plusieurs guides d'utilisation pour expliquer comment utiliser différents aspects de l'API.

Si nécessaire, vous pouvez également inclure un article de concepts intitulé « concepts de nom-de-lapi », qui fournit une explication de la théorie derrière les concepts liés à l'API que les développeur·euse·s doivent comprendre pour l'utiliser efficacement.

Ces articles doivent tous être créés en tant que sous-pages de la page de présentation de l'API. Par exemple, l'API Web Audio a quatre guides et un article de concepts :

Exemples

Vous devez créer quelques exemples qui démontrent au moins les cas d'utilisation les plus courants de l'API. Vous pouvez les placer n'importe où de manière appropriée, bien que l'endroit recommandé soit le dépôt GitHub de MDN (angl.).

Listez-les toutes

Créer une liste de toutes ces sous-pages est un bon moyen de les suivre. Par exemple :

  • Web_Audio_API

  • AudioContext

    • AudioContext.currentTime
    • AudioContext.destination
    • AudioContext.listener
    • …
    • AudioContext.createBuffer()
    • AudioContext.createBufferSource()
    • …

  • AudioNode

    • AudioNode.context
    • AudioNode.numberOfInputs
    • AudioNode.numberOfOutputs
    • …
    • AudioNode.connect(Param)
    • …

  • AudioParam

  • Évènements (mettre à jour la liste)

    • start
    • end
    • …

Chaque interface de la liste a une page distincte créée pour elle en tant que sous-page de https://developer.mozilla.org/fr/docs/Web/API ; par exemple, le document pour AudioContext est situé à https://developer.mozilla.org/fr/docs/Web/API/AudioContext. Chaque page d'interface explique ce que fait cette interface et fournit une liste des méthodes et propriétés qui la composent. Ensuite, chaque méthode et propriété est documentée sur sa propre page, qui est créée en tant que sous-page de l'interface dont elle est membre. Par exemple, BaseAudioContext/currentTime est documenté à https://developer.mozilla.org/fr/docs/Web/API/AudioContext/currentTime.

Créer les pages

Créez maintenant les pages dont vous avez besoin, selon les structures ci-dessous. Notre README du contenu MDN (angl.) contient des instructions sur la création d'un nouveau document, et notre guide Types de pages contient d'autres exemples et modèles de pages qui pourraient être utiles.

Structure d'une page de présentation

Les pages de destination des API varient considérablement en longueur, en fonction de la taille de l'API, mais elles ont toutes essentiellement les mêmes caractéristiques. Voir https://developer.mozilla.org/fr/docs/Web/API/Web_Audio_API pour un exemple de grande page de destination.

Les caractéristiques d'une page de départ sont décrites ci-dessous :

  1. Description : le premier paragraphe de la page de destination doit fournir une description courte et concise de l'objectif global de l'API.
  2. Section Concepts et utilisation : La section suivante doit être intitulée « [nom de l'API] concepts et utilisation » et fournir un aperçu de toutes les principales fonctionnalités que l'API offre, des problèmes qu'elle résout et de son fonctionnement — le tout à un niveau élevé. Cette section doit être assez courte et ne pas entrer dans le code ou les détails spécifiques de l'implémentation.
  3. Liste des interfaces : Cette section doit être intitulée « [nom de l'API] interfaces », et fournir des liens vers la page de référence pour chaque interface qui compose l'API, ainsi qu'une brève description de ce que chacune fait. Voir la section « Référencer d'autres fonctionnalités de l'API avec la macro {{DOMxRef}} » pour un moyen plus rapide de créer de nouvelles pages.
  4. Exemples : Cette section doit montrer un ou deux cas d'utilisation de l'API.
  5. Tableau des spécifications : À ce stade, vous devez inclure un tableau des spécifications — voir la section « Créer un tableau de référence des spécifications » pour plus de détails.
  6. Compatibilité des navigateurs : Vous devez maintenant inclure un tableau de compatibilité des navigateurs. Voir Tableaux de compatibilité pour plus de détails.
  7. Voir aussi : La section « Voir aussi » est un bon endroit pour inclure des liens supplémentaires qui peuvent être utiles lors de l'apprentissage de cette technologie, y compris des tutoriels MDN (et externes), des exemples, des bibliothèques, etc.

Structure d'une page d'interface

Vous devez maintenant être prêt·e à commencer à rédiger vos pages d'interface. Chaque page de référence d'interface doit respecter la structure suivante :

  1. {{APIRef}} : Incluez la macro {{APIRef}} dans la première ligne de chaque page d'interface, en incluant le nom de l'API comme argument, par exemple {{APIRef("Web Audio API")}}. Cette macro sert à construire un menu de référence sur le côté gauche de la page d'interface, incluant les propriétés et méthodes, ainsi que d'autres liens rapides tels que définis dans la macro GroupData (angl.) (demandez à quelqu'un d'ajouter votre API à une entrée GroupData existante, ou d'en créer une nouvelle, si elle n'est pas déjà répertoriée). Le menu ressemble à quelque chose comme la capture d'écran ci-dessous. Cette capture d'écran montre un menu de navigation vertical pour l'interface OscillatorNode, avec plusieurs sous-listes pour les méthodes et les propriétés, tel que généré par la macro APIRef

  2. Statut de la fonctionnalité : Une bannière indiquant le statut de la fonctionnalité (comme obsolète, non standard ou expérimental) est ajoutée automatiquement, si nécessaire. Pour cela, vous devez mettre à jour le statut dans le dépôt browser-compat-data.

  3. Description : le premier paragraphe de la page d'interface doit fournir une description courte et concise de l'objectif global de l'interface. Vous pouvez également inclure quelques paragraphes supplémentaires si une description supplémentaire est nécessaire. Si l'interface est en réalité un dictionnaire, vous devez utiliser ce terme au lieu de « interface ».

  4. Diagramme d'héritage : Utilisez la macro {{InheritanceDiagram}}(angl.) pour intégrer un diagramme d'héritage SVG pour l'interface.

  5. Liste des propriétés, Liste des méthodes : Ces sections doivent être intitulées « Propriétés » et « Méthodes », et fournir des liens (en utilisant la macro {{DOMxRef}}) vers une page de référence pour chaque propriété/méthode de cette interface, ainsi qu'une description de ce que chacune fait. Ces sections doivent être balisées en utilisant des listes de description/définition. Chaque description doit être courte et concise — une phrase si possible. Voir la section « Référencer d'autres fonctionnalités de l'API avec la macro {{DOMxRef}} » pour un moyen plus rapide de créer des liens vers d'autres pages.

    Au début des deux sections, avant le début de la liste des propriétés/méthodes, indiquez l'héritage en utilisant la phrase appropriée, en italique :

    • Cette interface n'implémente pas de propriétés spécifiques, mais hérite des propriétés de {{DOMxRef("XYZ")}}, et {{DOMxRef("XYZ2")}}.
    • Cette interface hérite également des propriétés de {{DOMxRef("XYZ")}}, et {{DOMxRef("XYZ2")}}.
    • Cette interface n'implémente pas de méthodes spécifiques, mais hérite des méthodes de {{DOMxRef("XYZ")}}, et {{DOMxRef("XYZ2")}}.
    • Cette interface hérite également des méthodes de {{DOMxRef("XYZ")}}, et {{DOMxRef("XYZ2")}}.

    Note : Les propriétés en lecture seule doivent utiliser la macro {{ReadOnlyInline}}, qui crée un petit badge « Lecture seule », inclus sur la même ligne que leurs liens {{DOMxRef}} (après l'utilisation des macros {{Experimental_Inline}}, {{Non-standard_Inline}} et {{Deprecated_Inline}}, si certaines de ces macros sont nécessaires).

  6. Exemples : Incluez une liste de code pour montrer l'utilisation typique d'une fonctionnalité majeure de l'API. Plutôt que de lister TOUT le code, vous devez lister un sous-ensemble intéressant. Pour une liste complète de code, vous pouvez référencer un dépôt GitHub (angl.) contenant l'exemple complet, et vous pouvez également créer un lien vers un exemple en direct utilisant la fonctionnalité GitHub gh-pages (angl.) (à condition qu'il utilise uniquement du code côté client, bien sûr). Si l'exemple est visuel, vous pouvez également utiliser la fonctionnalité MDN Live Sample pour le rendre interactif et jouable dans la page.

  7. Tableau des spécifications : À ce stade, vous devez inclure un tableau des spécifications — voir la section « Créer un tableau de référence des spécifications » pour plus de détails.

  8. Compatibilité des navigateurs : Vous devez maintenant inclure un tableau de compatibilité des navigateurs. Voir Tableaux de compatibilité pour plus de détails.

  9. Prothèses d'émulation : Le cas échéant, incluez cette section, en fournissant du code pour une prothèse d'émulation qui permet d'utiliser l'API même sur les navigateurs qui ne l'implémentent pas. Si aucune prothèse d'émulation n'existe ou n'est nécessaire, laissez cette section de côté.

  10. Voir aussi : La section « Voir aussi » est un bon endroit pour inclure des liens supplémentaires qui peuvent être utiles pour apprendre cette technologie, y compris des tutoriels MDN (et externes), des exemples, des bibliothèques, etc. Nous avons une politique libérale pour les liens vers des sources externes, mais faites attention :

    • Ne pas inclure de pages contenant les mêmes informations qu'une autre page de MDN ; liez plutôt cette page.
    • Ne pas mettre de noms d'auteur·ice·s — nous sommes un site de documentation neutre. Liez au document ; le nom de l'auteur·ice y est affiché.
    • Faites particulièrement attention aux articles de blog : ils ont tendance à devenir obsolètes (ancienne syntaxe, informations de compatibilité incorrectes). Ne les liez que s'ils ont une valeur ajoutée claire qui ne peut pas être trouvée dans un document maintenu.
    • N'utilisez pas de verbes d'action comme « Voir … pour plus d'informations » ou « Cliquez pour… », vous ne savez pas si votre lecteur·ice est capable de voir ou de cliquer sur le lien (comme sur une version papier du document).

Exemples de pages d'interface

Les exemples suivants sont des exemples de pages d'interface :

Structure d'une page de propriété

Créez vos pages de propriété en tant que sous-pages de l'interface sur laquelle elles sont implémentées. Copiez la structure d'une autre page de propriété pour servir de base à votre nouvelle page.

Modifiez le nom de la page de propriété pour suivre la convention Interface.property_name.

Les pages de propriété doivent comporter les sections suivantes :

  1. Titre : le titre de la page doit être InterfaceName : propriété propertyName. Le nom de l'interface doit commencer par une majuscule. Bien qu'une interface soit implémentée en JavaScript sur le prototype des objets, nous n'incluons pas .prototype. dans le titre, comme nous le faisons dans la référence JavaScript.

  2. {{APIRef}} : Incluez la macro {{APIRef}} dans la première ligne de chaque page de propriété, en incluant le nom de l'API en argument, par exemple {{APIRef("Web Audio API")}}. Cette macro sert à construire un menu de référence sur le côté gauche de la page de l'interface, incluant les propriétés et méthodes, ainsi que d'autres liens rapides tels que définis dans la macro GroupData (angl.) (demandez à quelqu'un d'ajouter votre API à une entrée GroupData existante, ou d'en créer une nouvelle, si elle n'est pas déjà répertoriée). Le menu ressemble à quelque chose comme la capture d'écran ci-dessous. Cette capture d'écran montre un menu de navigation vertical pour l'interface OscillatorNode, avec plusieurs sous-listes pour les méthodes et les propriétés, tel que généré par la macro APIRef

  3. Statut de la fonctionnalité : Une bannière indiquant le statut de la fonctionnalité (comme obsolète, non standard ou expérimental) est ajoutée automatiquement, si nécessaire. Pour cela, vous devez mettre à jour le statut dans le dépôt browser-compat-data.

  4. Description : le premier paragraphe de la page de propriété doit fournir une description courte et concise de l'objectif général de la propriété. Vous pouvez également inclure quelques paragraphes supplémentaires si une description supplémentaire est nécessaire. Les informations supplémentaires évidentes à inclure sont sa valeur par défaut/initiale et si elle est en lecture seule ou non. La structure de la première phrase doit être :

    Pour les propriétés en lecture seule

    La propriété en lecture seule InterfaceName.property retourne un {{DOMxRef("type")}} qui…

    Pour les autres propriétés

    La propriété InterfaceName.property est un {{DOMxRef("type")}} qui…

    Note : InterfaceName.property doit être en <code>, et doit également être en gras (<strong>) la première fois qu'il est utilisé.

  5. Valeur : La section Valeur contient une description de la valeur de la propriété. Cela doit inclure le type de données de la propriété et ce qu'elle représente. Pour un exemple, voir SpeechRecognition.grammars

  6. Exemples : Incluez une liste de code pour montrer l'utilisation typique de la propriété en question. Vous devez commencer par un exemple simple qui montre comment un objet du type est créé et comment accéder à la propriété. Des exemples plus complexes peuvent être ajoutés après un tel exemple. Dans ces exemples supplémentaires, plutôt que de lister tout le code, vous devez lister un sous-ensemble intéressant de celui-ci. Pour une liste complète de code, vous pouvez référencer un dépôt GitHub (angl.) contenant l'exemple complet, et vous pouvez également créer un exemple en direct en utilisant la fonction GitHub gh-pages (angl.) (à condition qu'il utilise uniquement du code côté client bien sûr). Si l'exemple est visuel, vous pouvez également utiliser la fonctionnalité MDN Live Sample pour le rendre interactif et jouable dans la page.

  7. Tableau des spécifications : À ce stade, vous devez inclure un tableau des spécifications — voir la section « Créer un tableau de référence des spécifications » pour plus de détails.

  8. Compatibilité des navigateurs : Vous devez maintenant inclure un tableau de compatibilité des navigateurs. Voir Tableaux de compatibilité pour plus de détails.

  9. Voir aussi : La section « Voir aussi » est un bon endroit pour inclure des liens supplémentaires qui peuvent être utiles lors de l'utilisation de cette technologie : comme les méthodes et propriétés affectées par un changement de cette propriété ou les évènements déclenchés en relation avec celle-ci. D'autres liens utiles pour apprendre cette technologie, y compris des tutoriels MDN (et externes), des exemples, des bibliothèques,… peuvent être ajoutés, bien qu'il puisse être utile de les ajouter plutôt sur la page de référence de l'interface.

Exemples de pages de propriétés

Les exemples suivants sont des exemples de pages de propriétés :

Structure d'une page de méthode

Créez vos pages de méthode en tant que sous-pages de l'interface sur laquelle elles sont implémentées. Copiez la structure d'une autre page de méthode pour servir de base à votre nouvelle page.

Les pages de méthode doivent inclure les sections suivantes :

  1. Titre : le titre de la page doit être InterfaceName : méthode method() (avec les deux parenthèses terminales), mais le slug (la fin de l'URL de la page) ne doit pas inclure les parenthèses. De plus, le nom de l'interface doit commencer par une majuscule. Bien qu'une interface soit implémentée en JavaScript sur le prototype des objets, nous ne mettons pas .prototype. dans le titre, comme nous le faisons dans la référence JavaScript.

  2. {{APIRef}} : Incluez la macro {{APIRef}} dans la première ligne de chaque page de méthode, en incluant le nom de l'API en argument, par exemple {{APIRef("Web Audio API")}}. Cette macro sert à construire un menu de référence sur le côté gauche de la page de l'interface, incluant les propriétés et méthodes, ainsi que d'autres liens rapides tels que définis dans la macro GroupData (angl.) (demandez à quelqu'un d'ajouter votre API à une entrée GroupData existante, ou d'en créer une nouvelle, si elle n'est pas déjà répertoriée). Le menu ressemble à quelque chose comme la capture d'écran ci-dessous. Cette capture d'écran montre un menu de navigation vertical pour l'interface OscillatorNode, avec plusieurs sous-listes pour les méthodes et les propriétés, tel que généré par la macro APIRef

  3. Statut de la fonctionnalité : Une bannière indiquant le statut de la fonctionnalité (comme obsolète, non standard ou expérimental) est ajoutée automatiquement, si nécessaire. Pour cela, vous devez mettre à jour le statut dans le dépôt browser-compat-data.

  4. Description : Le premier paragraphe de la page de méthode doit fournir une description courte et concise de l'objectif général de la méthode. Vous pouvez également inclure quelques paragraphes supplémentaires si une description supplémentaire est nécessaire. Les informations supplémentaires évidentes à inclure sont les valeurs par défaut des paramètres, toute théorie sur laquelle la méthode repose et ce que font les valeurs des paramètres.

    Le début de la première phrase doit suivre la structure suivante :

    La méthode InterfaceName.method() …

    Note : InterfaceName.method() doit être en <code>, et doit également être en gras (<strong>) la première fois qu'il est utilisé.

  5. Syntaxe : La section de syntaxe doit inclure un exemple de 2 à 3 lignes — généralement juste la construction de l'interface, puis l'appel de la méthode de l'interface.

    La syntaxe doit être de la forme suivante :

    method(param1, param2, …)

    La section de syntaxe doit inclure trois sous-sections (voir SubtleCrypto.sign() pour un exemple) :

    • « Paramètres » : Elle doit contenir une liste de définition (ou une liste non ordonnée) qui nomme et décrit les différents paramètres que la méthode prend. Vous devez inclure la macro Facultatif à côté du nom du paramètre, dans le cas de paramètres optionnels. S'il n'y a pas de paramètres, cette section doit être omise.
    • « Valeur de retour » : Elle doit indiquer quelle valeur de retour la méthode a, qu'il s'agisse d'une valeur simple comme un double ou un booléen, ou d'une valeur plus complexe comme un autre objet d'interface, auquel cas vous pouvez utiliser la macro {{DOMxRef}} pour créer un lien vers la page MDN couvrant cette interface (si elle existe). Une méthode peut ne rien retourner, auquel cas la valeur de retour doit être écrite comme « {{JSxRef('undefined')}} » (ce qui apparaît ainsi dans la page rendue : undefined).
    • « Exceptions » : Elle doit lister les différentes exceptions qui peuvent être levées lors de l'invocation de la méthode, et dans quelles circonstances elles se produisent. S'il n'y a pas d'exceptions, cette section doit être omise.

  6. Exemples : Incluez une liste de code pour montrer l'utilisation typique de la méthode en question. Plutôt que de lister tout le code, vous devez lister un sous-ensemble intéressant. Pour une liste complète de code, vous devez référencer un dépôt GitHub (angl.) contenant l'exemple complet, et vous pouvez également créer un lien vers un exemple en direct utilisant la fonctionnalité GitHub gh-pages (angl.) (à condition qu'il n'utilise que du code côté client bien sûr). Si l'exemple est visuel, vous pouvez également utiliser la fonctionnalité MDN d'exemples interactifs pour le rendre interactif et jouable dans la page.

  7. Tableau des spécifications : À ce stade, vous devez inclure un tableau des spécifications — voir la section « Créer un tableau de référence des spécifications » pour plus de détails.

  8. Compatibilité des navigateurs : Vous devez maintenant inclure un tableau de compatibilité des navigateurs. Voir Tableaux de compatibilité pour plus de détails.

Exemples de pages de méthodes

Les exemples suivants sont des exemples de pages de méthodes :

Barres latérales

Une fois que vous avez créé vos pages de référence API, vous devez insérer les barres latérales correctes pour les associer ensemble. Notre guide sur les barres latérales de référence API explique comment faire.

Aider à améliorer MDN

Apprendre à contribuer

Cette page a été modifiée le par les contributeur·ice·s du MDN.

Voir cette page sur GitHub • Signaler un problème avec ce contenu