Comment lire la documentation de l’API pour les newbs?

Je lis le guide de script JavaScript pour Photoshop, Illustrator et InDesign. L’API est très difficile à lire car elle suppose que je connais certaines conventions abrégées. Le problème ne se limite pas à ce guide de script particulier. Je pourrais énumérer des dizaines qui présentent le même problème.

Lorsque je lis une API en tant que personne qui ne vit pas dans le code 24 heures sur 24, je veux chercher quelque chose et voir un exemple simple du code en action dans la forme la plus élémentaire. Mais souvent, il n’est pas facile de le comprendre au début.

Voici un exemple. Je cherche comment changer la couleur d’un élément en JavaScript dans Photoshop. Je recherche donc le PDF et trouve “fillColor”. Je trouve ça dans les docs:

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

Quand je lis ceci, à première vue, cela n’a aucun sens. Pourquoi y a-t-il des parenthèses et comment saurais-je que je ne suis pas censé les utiliser dans une implémentation? Pourquoi les virgules sont entre parenthèses? Je sais ce que le code devrait ressembler d’un échantillon que j’ai trouvé, qui est le suivant:

 myPath.fillPath(myNewColor)

Si je n’avais pas vu l’exemple, je ne devinerais JAMAIS à partir du code de l’API que c’est ainsi que cette méthode devrait ressembler une fois implémentée. Quelqu’un d’autre a souligné qu’un exemple étendu pour cette méthode pourrait ressembler à ceci:

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

D’ACCORD. Je vois que je peux laisser de côté les parameters facultatifs implicites. Bien. Mais encore une fois, je n’aurais JAMAIS deviné cela de l’API.

Y a-t-il quelque part un document mystérieux qui indique aux utilisateurs comment lire la documentation de l’API? Pourquoi est-ce écrit comme ça? Quelles connaissances préalables suppose-t-il? Pourquoi est-ce comme ça, et que puis-je faire pour ne plus m’interroger et pour le “récupérer”, afin que je puisse lire et implémenter plus facilement la prochaine API?

Alors, pourquoi la documentation de l’API est-elle écrite de manière à confondre les newbs / hackers / bricoleurs pérennes comme moi?

Ce n’est vraiment pas destiné à être écrit de cette façon. Je conviens qu’il ne semble pas y avoir de facilité d’utilisation entre les documentations API. Cependant, il y a beaucoup de recoupements entre les conventions de syntaxe de style man plus ancien man conventions API / espace de noms modernes.

En règle générale, le type de personne qui travaille avec l’API aura des connaissances de base en développement ou, tout au moins, en «utilisateur privilégié». Ces types d’utilisateurs sont habitués à de telles conventions de syntaxe et il est plus logique que le document de l’API suive que d’essayer d’en créer de nouveaux.

Y a-t-il quelque part un document mystérieux qui indique aux utilisateurs comment lire la documentation de l’API?

Il n’y a vraiment pas de norme, ni de RFC, supersekretsyntaxdoc qui existe partout, mais il existe un fichier datant d’ environ 30 ans pour le format de page de manuel UNIX , qui est largement utilisé.

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

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

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

Les ellipses … sont utilisées pour montrer que le prototype d’argument précédent peut être répété.

Un argument commençant par un signe moins – est souvent considéré comme une sorte d’argument de drapeau, 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, depuis Python , les pages de manuel , les bibliothèques javascript ( Highcharts ), etc.

Briser 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 y transférer n’importe fillPath() de ces parameters. Les virgules dans l’option [] signifient que si ce paramètre est utilisé en plus des autres, vous avez besoin de la virgule pour le séparer. (Le sens commun parfois, bien sûr, mais parfois certains langages comme VB, ont explicitement besoin de ces virgules pour délimiter correctement le paramètre qui manque!). Étant donné que vous n’avez pas créé de lien vers la documentation (et que je ne le trouve pas sur la page de script d’Adobe ), il n’existe pas vraiment de moyen de savoir quel format est attendu par l’API Adobe. 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 manières:

 fillPath() //Nothing passed fillPath(#000000,RGB) // Black, in RGB mode fillPath(#000000,RGB,50) // Black, in RGB mode, half opacity //Now it gets sortingcky, this might ALSO be acceptable: fillPath(#000000,50) // Black, no mode, half opacity //OR fillPath(#000000,,50) // Black, no mode, half opacity

Là encore, il existe généralement des normes pour toutes les documentations relatives aux API / programmation. Cependant, dans chaque document, il pourrait y avoir des différences subtiles. En tant qu’utilisateur expérimenté ou développeur, vous DEVEZ pouvoir lire et comprendre les documents / frameworks / bibliothèques que vous tentez d’utiliser.

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

A propos des parenthèses et autres, il y a généralement une section de 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 devriez les connaître pour comprendre la plupart des notations.

Les parenthèses 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 du lecteur, 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

Loic http://www.loicaigon.com

J’ai eu cette même question il y a quelques temps et quelqu’un m’a montré la forme étendue de Backus – Naur .

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 J’ai été utile, mais une fois que vous avez lu la syntaxe sous-jacente, vous pouvez créer votre propre code.