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

103

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
})
Dbonneville
la source
4
Existe-t-il une introduction au document de référence des API qui décrit leurs conventions syntaxiques?
Greg Hewgill
35
Pour la personne qui a voté pour la fermeture: je pense que cette question a du mérite, et je "voterais pour ne pas fermer" si je le pouvais. Ce n'est pas une question que j'ai vue (ou entendue) posée auparavant, elle aborde un problème légitime lié à la programmation, et je trouverais personnellement la réponse utile lorsque j'enseigne des choses liées à la programmation.
David Wolever
4
Derek: Je pense que vous avez manqué l'une des phrases en gras du message original. Si vous recherchez sur Google "Comment lire la documentation de l'API", les informations des 10 premiers résultats indiquent des choses comme "abstrait", "incomplet", "déroutant", etc., renforçant ainsi le point de ma question.
dbonneville
2
Greg: Il n'y a pas d'introduction aux produits Photoshop / Adobe. Ils suivent tous le même format en 2 PDF par produit. Les autres API auxquelles je pense font de même. Il y a une connaissance implicite que je n'ai pas dans de nombreux cas et que je voudrais certainement.
dbonneville
1
Une ressource utile est le visualiseur d'objets intégré à Extendscript IDE (appuyez sur F1). Cliquer sur un objet vous montrera les propriétés et les méthodes dont il dispose. De plus, s'il utilise d'autres objets comme paramètres, il est (généralement) lié à eux afin que vous puissiez voir quelles propriétés ils ont également. Ce n'est pas parfait mais ça aide.
pdizz

Réponses:

92

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.

PingouinCoder
la source
5
Le lien au format de synopsis de la page de manuel UNIX est mort - quelqu'un a-t-il un lien de remplacement? @PenguinCoder Update: Basé sur [ unix.stackexchange.com/questions/17833/… (Unix Stack Exchange), il est vaguement basé sur [ en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_Form (EBNF)
steviejay
Il existe une copie archivée du format de synthèse de page de manuel
CodeManX
5

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.

fortran
la source
3

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
Loic Aigon
la source
2
fillPath (mode)ça va peut-être. Si un argument optionnel précède un argument non optionnel, cela signifie souvent que la fonction est suffisamment intelligente pour détecter si l'argument optionnel a été donné ou non (par exemple en regardant son type)
ThiefMaster
1
MMmm ben c'est possible mais je préfère m'appuyer sur quelque chose de fort que ce que le script pourrait faire pour moi: D
Loic Aigon
1

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.

StevenKW
la source