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

Question

Je suis en train de lire à travers le JavaScript guide des scripts pour Photoshop, Illustrator et InDesign. L'API est vraiment difficile à lire car il suppose je sais que certains d'abréviation conventions. Le problème n'est pas limité à ce guide des scripts. Je pourrais énumérer des dizaines qui présentent le même problème.

Quand j'ai lu une API comme quelqu'un qui ne vit pas dans le code 24 heures par jour, je veux ressembler à quelque chose et de voir un exemple simple de l'utilisation du code dans la forme la plus basique. Mais souvent, il n'est pas facile à comprendre au premier abord.

Ici est un exemple. Je vais chercher comment changer la couleur d'un élément en JavaScript dans Photoshop. Donc, je recherche le fichier PDF et de trouver des "fillColor". J'ai trouve cela dans les docs:

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

Quand je lis cela, à première vue, n'a aucun sens. Pourquoi il y a des crochets et comment je sais que je ne suis pas censé les utiliser dans une mise en œuvre? Pourquoi sont des virgules dans les crochets? Je sais ce que le code devrait ressembler à partir d'un échantillon que j'ai trouvé, qui est-ce:

myPath.fillPath(myNewColor)

Si je n'avais pas vu l'exemple, je n'aurais JAMAIS la divine du code de l'API que c'est la façon dont cette méthode doit regarder lors de la mise en œuvre. Quelqu'un d'autre a fait remarquer qu'un exemple de cette méthode pourrait ressembler à ceci:

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

OK. Je vois que je peux laisser implicite des paramètres facultatifs. Des beaux. Mais encore une fois, je n'aurais JAMAIS deviné ce à partir de l'API.

Donc, est-il un mystérieux document quelque part qui dit aux gens comment lire la documentation de l'API? Pourquoi est-il écrit comme ça? Quelles sont les connaissances antérieures ne présume-je? Pourquoi est-il comme cela, et ce que je peux faire pour arrêter de me demander à ce sujet et "get", donc je peut plus heureux de lire et de mettre en œuvre la prochaine API?

Alors, pourquoi est-documentation de l'API écrite de manière à confondre vivaces newbs / les pirates / les Bricoleurs comme moi?

Answer 1

Alors, pourquoi est-documentation de l'API écrite de manière à confondre vivaces newbs / les pirates / les Bricoleurs comme moi?

C'est vraiment pas destiné à être écrit de cette façon. Je suis d'accord il ne semble pas que la facilité d'utilisation à l'échelle de la documentation de l'API. Cependant, il y a beaucoup de croisements à partir d'anciennes man style de conventions de syntaxe, à la modernité de l'API/espace de noms conventions.

Typiquement, le genre de personne qui travaille avec l'API, aura de l'expérience en développement ou à tout le moins un "power user". Ces types d'utilisateurs sont habitués à ce genre de conventions de syntaxe et il fait plus de sens pour l'API de document à suivre que d'essayer d'en créer de nouveaux.

Est-il un mystérieux document quelque part qui dit aux gens comment lire la documentation de l'API?

Il n'y a vraiment pas de norme, ou RFC, supersekretsyntaxdoc autour de la pose n'importe où, cependant, il est ~30 ans de fichiers pour UNIX page de man synposis format qui est largement utilisé.

Quelques exemples de cela (et pour répondre à votre question) serait :

Mots soulignés sont considérés comme des littéraux, et sont tapé tout comme ils apparaissent.

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

Des points de suspension ... sont utilisés pour montrer que l'argument précédent-prototype peut être répété.

Un argument début du signe " - est souvent pris pour signifier une sorte de drapeau argument, même s'il apparaît dans une position où un nom de fichier peut apparaître.

Presque tous les programmes relatifs à la documentation utilise ce type de syntaxe de la convention, à partir de Python, des pages de man, javascript libs (Highcharts), etc.

---

Briser votre exemple à partir d'Adobe API

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

Nous voyons qu' fillPath() (une fonction) prend un argument optionnel fillColor, mode, opacity, preserveTransparency, feathe, wholePath ou antiAlias. Appelant fillPath(), vous pouvez passer n'importe où à partir d'aucun, à tous, de ces paramètres. Les virgules dans l'option [] signifie que si ce paramètre est utilisé en plus des autres, vous avez besoin de la virgule pour séparer les il. (Le sens commun, parfois, bien sûr, mais parfois, certaines langues comme le VB, explicitement besoin de ces virgules pour délimiter correctement le paramètre est manquant!). Puisque vous n'avez pas de lien vers la documentation (et je ne le trouve pas sur Adobe script de la page) il n'y a vraiment pas moyen de savoir quel format Adobe API attend. Cependant, il devrait y avoir une explication au sommet de la plupart de la documentation sur les conventions utilisées dans.

Donc, cette fonction pourrait probablement être utilisé de nombreuses 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 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 n'y a habituellement certaines normes dans toutes les documentations relatives à l'API de programmation. Cependant, dans chaque doc, il pourrait y avoir des différences subtiles. Comme un utilisateur de puissance, ou développeur, vous ÊTES censé être en mesure de lire et de comprendre les documents/frameworks/librairies vous tentez d'utiliser.

Answer 2

Les docs de l'API pour typées dynamiquement langues peut être pas très significatif si pas écrit avec soin, afin de ne pas se sentir trop mal à ce sujet, même les plus aguerris développeur peut avoir un moment difficile essayer de les comprendre.

À propos de crochets et un tel, il est généralement un code de la section conventions qu'il faut expliquer exactement utilisation à l'extérieur littérale des exemples; bien que EBNF, Regex et de chemin de Fer Diagrammes sont presque omniprésents, de sorte que vous devez être familier avec eux afin de comprendre la plupart des notations.

Answer 3

Les supports de dire que la propriété est facultative. Sachez cependant que si vous souhaitez définir un certain bien à la nième rang, vous devez déclarer les propriétés de la po de l'une ou de les déclarer comme non défini :

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