Comment interpréter les paramètres de la fonction de documentation de l'API?

Existe-t-il une norme pour interpréter la syntaxe des interfaces de fonction dans les documentations API et si oui, comment est-elle définie?

Voici un exemple de modification de la couleur d'un élément dans le guide de script JavaScript de Photoshop pour la fonction "fillColor":

fillPath
([fillColor]
[, mode]
[, opacity]
[, preserveTransparency] [, feather]
[, wholePath] [, antiAlias])

Quelle est la signification des crochets et pourquoi y a-t-il des virgules entre crochets? Comment cela se rapporte-t-il aux exemples d'appels suivants?

myPath.fillPath(myNewColor)

myPath.fillPath(mynewColor, {
    mode: RGB,
    opacity: .5
})

Alors pourquoi la documentation de l'API est-elle écrite de manière à confondre les novices / hackers / bricoleurs éternels comme moi?

Ce n'est vraiment pas censé être écrit de cette façon. Je conviens qu'il ne semble pas y avoir de facilité d'utilisation dans les documentations API. Cependant, il y a beaucoup de croisements entre les anciennes manconventions de syntaxe de style et les conventions modernes d'API / d'espace de noms.

En règle générale, le type de personne qui travaille avec l'API, aura une certaine expérience en développement ou au moins un «utilisateur expérimenté». Ces types d'utilisateurs sont habitués à de telles conventions de syntaxe et il est plus logique que le document API suive que d'essayer d'en créer de nouveaux.

Y a-t-il quelque part un document mystérieux qui explique aux gens comment lire la documentation de l'API?

Il n'y a vraiment pas de supersekretsyntaxdoc standard ou RFC, mais il existe un fichier vieux d'environ 30 ans pour le format de synthèse des pages de manuel UNIX qui est largement utilisé.

Quelques exemples de ceci (et répondre à votre question) seraient:

Les mots soulignés sont considérés comme des littéraux et sont tapés tels qu'ils apparaissent.

Les crochets ([]) autour d'un argument indiquent que l'argument est facultatif.

Les ellipses ... sont utilisées pour montrer que l'argument-prototype précédent peut être répété.

Un argument commençant par un signe moins - est souvent pris comme signifiant une sorte d'argument indicateur même s'il apparaît à une position où un nom de fichier pourrait apparaître.

Presque toute la documentation relative à la programmation utilise ce type de convention de syntaxe, à partir de Python , des pages de manuel , des bibliothèques javascript ( Highcharts ), etc.

Décomposer votre exemple de l'API Adobe

fillPath
([fillColor]
[, mode]
[, opacity]
[, preserveTransparency] [, feather]
[, wholePath] [, antiAlias])

On voit que fillPath()(une fonction) prend des arguments optionnels fillColor, mode, opacity, preserveTransparency, feathe, wholePathou antiAlias. En appelant fillPath(), vous pouvez lui passer n'importe où de aucun, à tous. Les virgules à l'intérieur de l'option facultative []signifient que si ce paramètre est utilisé en plus d'autres, vous avez besoin de la virgule pour le séparer. (Parfois le bon sens, bien sûr, mais parfois certaines langues comme VB, ont explicitement besoin de ces virgules pour délimiter correctement le paramètre manquant!). Puisque vous n'avez pas de lien vers la documentation (et je ne la trouve pas sur la page de script d'Adobe ), il n'y a vraiment pas de moyen de savoir à quel format l'API Adobe attend. Cependant, il devrait y avoir une explication en haut de la plupart des documents expliquant les conventions utilisées dans.

Donc, cette fonction pourrait probablement être utilisée de plusieurs façons:

fillPath() //Nothing passed
fillPath(#000000,RGB) // Black, in RGB mode
fillPath(#000000,RGB,50) // Black, in RGB mode, half opacity

//Now it gets tricky, this might ALSO be acceptable:
fillPath(#000000,50) // Black, no mode, half opacity

//OR
fillPath(#000000,,50) // Black, no mode, half opacity

Encore une fois, il existe généralement des normes dans toutes les documentations relatives à l'API / à la programmation. Cependant, dans chaque document, il pourrait y avoir des différences subtiles. En tant qu'utilisateur expérimenté ou développeur, on s'attend à ce que vous soyez capable de lire et de comprendre les documents / frameworks / bibliothèques que vous essayez d'utiliser.

Les documents d'API pour les langages à typage dynamique peuvent ne pas être très significatifs s'ils ne sont pas écrits avec soin, alors ne vous sentez pas trop mal à ce sujet, même le développeur le plus expérimenté peut avoir du mal à les comprendre.

À propos des crochets et autres, il existe généralement une section sur les conventions de code qui devrait expliquer l'utilisation exacte en dehors des exemples littéraux; bien que les diagrammes EBNF , Regex et Railroad soient presque omniprésents, vous devez donc vous familiariser avec eux pour comprendre la plupart des notations.

Les crochets signifient que la propriété est facultative. Sachez cependant que si vous souhaitez définir une propriété au rang nTh, vous devez soit déclarer les propriétés de la première, soit les déclarer comme non définies:

fillPath() //good
fillPath ( someFillColor ) //good
fillPath ( someFillColor, mode ) //good
fillPath ( undefined, mode ) //good
fillPath ( mode ) //bad
fillPath ( undefined ) //really bad

J'ai eu cette même question il y a quelque temps et quelqu'un m'a pointé vers Extended Backus – Naur Form .

Cela a du sens car la programmation peut être utilisée pour créer des résultats potentiellement illimités. La documentation ne peut pas afficher un exemple pour chaque cas possible. Un bon exemple d'utilisation courante est utile, mais une fois que vous pouvez lire la syntaxe sous-jacente, vous pouvez créer votre propre code.