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 sur la façon de changer la couleur d'un élément dans le guide de script JavaScript pour 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? Quel est le lien avec les 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 newbs/hackers/DIYers pérennes 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 croisement entre les anciennes conventions de syntaxe de style man et les conventions modernes de l'API/espace de noms.
En règle générale, le type de personne qui travaille avec l'API aura des antécédents 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 pour le document API de suivre 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, partout, mais il existe un fichier de ~ 30 ans pour UNIX format de page de manuel qui est largement utilisé.
Voici quelques exemples de cela (et répondant à votre question):
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 considéré comme signifiant une sorte d'argument indicateur même s'il apparaît dans une position où un nom de fichier peut apparaître.
Presque toute la documentation relative à la programmation utilise ce type de convention de syntaxe, à partir de Python , pages de manuel , bibliothèques javascript ( Highcharts ), etc.
Décomposer votre exemple à partir de l'API Adobe
fillPath
([fillColor]
[, mode]
[, opacity]
[, preserveTransparency] [, feather]
[, wholePath] [, antiAlias])
Nous voyons que fillPath() (une fonction) prend des arguments optionnels fillColor, mode, opacity, preserveTransparency, feathe, wholePath Ou antiAlias. En appelant fillPath(), vous pouvez lui passer n'importe où, de aucun à tous ces paramètres. Les virgules dans le [] Facultatif signifient que si ce paramètre est utilisé en plus des autres, vous avez besoin de la virgule pour le séparer. (Le bon sens parfois, bien sûr, mais parfois certaines langues comme VB, ont explicitement besoin de ces virgules pour bien délimiter le paramètre manquant!). Étant donné que vous n'avez pas établi de lien vers la documentation (et je ne la trouve pas sur page de script d'Adobe ), il n'y a vraiment aucun moyen de savoir quel format l'API Adobe attend. Cependant, il devrait y avoir une explication en haut de la documentation la plupart expliquant les conventions utilisées.
Ainsi, 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/programmation. Cependant, dans chaque doc, il pourrait y avoir de subtiles différences. En tant qu'utilisateur expérimenté ou développeur, vous ÊTES censé être capable de lire et de comprendre les documents/frameworks/bibliothèques que vous essayez d'utiliser.
Les documents d'API pour les langages typés dynamiquement 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 à essayer de 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 EBNF , Regex et Railroad Diagrams sont presque omniprésents, vous devez donc les connaître pour comprendre la plupart des notations.
Les crochets signifient que la propriété est facultative. Sachez cependant que si vous souhaitez définir la propriété soem au rang nTh, vous devez soit déclarer les propriétés de la première soit les déclarer 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 montré 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 d'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.