¿Cómo leer la documentación de API para newbs?

Question

Estoy leyendo a través de la guía de scripts de JavaScript para Photoshop, Illustrator e InDesign. La API es realmente difícil de leer porque supone que sé ciertas convenciones de taquigrafía. El problema no está limitado a esta guía de scripting en particular. Podría enumerar docenas que presentan el mismo problema.

Cuando leo una API como alguien que no vive en el código las 24 horas del día, quiero buscar algo y ver un ejemplo simple del código en acción en la forma más básica. Pero a menudo no es fácil darle sentido al principio.

Aquí hay un ejemplo. Estoy buscando cómo cambiar el color de un elemento por JavaScript en Photoshop. Entonces busco el PDF y encuentro "fillColor". Encuentro que esta en la documentación:

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

Cuando leí esto, que a primera vista no tiene sentido. ¿Por qué hay corchetes y cómo sabría que se supone que no debo usarlos en una implementación? ¿Por qué las comas están entre paréntesis? Yo sé lo que el código debe se parece a partir de una muestra que encontré, que es la siguiente:

myPath.fillPath(myNewColor) 

Si no hubiera visto el ejemplo, yo nunca divina a partir del código API que es la forma en que este método debería mirar cuando se implemente. Otra persona señaló que un ejemplo extendido para este método podría verse así:

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

OK. Veo que puedo omitir los parámetros opcionales implícitos. Multa. Pero, de nuevo, NUNCA lo hubiera adivinado de la API.

Entonces, ¿hay algún documento misterioso en alguna parte que le diga a la gente cómo leer la documentación de la API? ¿Por qué está escrito así? ¿Qué conocimiento previo supone que tengo? ¿Por qué es así y qué puedo hacer para dejar de preguntarme sobre eso y "obtenerlo" para poder leer e implementar la próxima API?

¿Por qué la documentación de la API está escrita de tal manera que confunde perennes newbs/hackers/DIYers como yo?

Answer 1

¿Por qué la documentación de la API está escrita de tal manera que confunde a los newb/peleadores/DIYers perennes como yo?

Realmente no está destinado a ser escrito de esa manera.Estoy de acuerdo en que no parece ser fácil de usar en la documentación de API. Sin embargo, hay una gran cantidad de cruces de las antiguas convenciones de sintaxis de estilo man, a las convenciones modernas API/namespace.

Normalmente, el tipo de persona que trabaja con API tendrá algunos antecedentes en el desarrollo o, al menos, un "usuario avanzado". Estos tipos de usuarios están acostumbrados a tales convenciones de sintaxis y tiene más sentido que siga el documento de la API que tratar de crear otros nuevos.

¿Hay algún documento misterioso en alguna parte que le diga a la gente cómo leer la documentación de la API?

Realmente no hay ninguna norma o RFC, supersekretsyntaxdoc por ahí en cualquier lugar, sin embargo hay un archivo ~ 30 años de edad para UNIX man page synposis format que es de uso generalizado.

Algunos ejemplos de esto (y respondiendo a su pregunta) sería:

Las palabras subrayadas son considerados literales, y se escriben tal y como aparecen.

Los corchetes ([]) alrededor de un argumento indican que el argumento es opcional.

Elipses ... se usan para mostrar que el argumento anterior prototipo puede repetirse.

Un argumento que comienza con un signo menos - a menudo se considera que significa algún tipo de argumento de indicador, incluso si aparece en una posición donde podría aparecer un nombre de archivo.

Casi toda la documentación relacionada programación utiliza este tipo de convenciones de sintaxis, Python, man pages, javascript libs (Highcharts), etc.

---

Romper el ejemplo de Adobe API

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

Vemos que fillPath() (una función) toma los argumentos opcionales fillColor, mode, opacity, preserveTransparency, feathe, wholePath o antiAlias. Llamando al fillPath(), podría pasar de ninguno a todos esos parámetros. Las comas dentro del [] opcional significan que si este parámetro se usa además de otros, necesita la coma para separarlo. (Algunas veces, el sentido común, pero a veces algunos lenguajes, como VB, necesitan explícitamente esas comas para delinear correctamente qué parámetro falta). Como no se ha vinculado a la documentación (y no puedo encontrarla en Adobe's scripting page), realmente no hay forma de saber qué formato espera la API de Adobe. Sin embargo, debe haber una explicación en la parte superior de más documentación que explique las convenciones utilizadas dentro.

Por lo tanto, esta función probablemente podría ser utilizado de muchas maneras:

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 

Una vez más, por lo general hay algunas normas en todas las documentaciones relativas a la API/programación. Sin embargo, en cada documento, podría haber diferencias sutiles. Como usuario avanzado o desarrollador, se espera que pueda leer y comprender los documentos/marcos/bibliotecas que intenta utilizar.

Answer 2

Los corchetes significan que la propiedad es opcional. Tenga en cuenta sin embargo que si desea establecer la propiedad soem en la fila n, usted tiene que o bien declarar propiedades para la eading uno o declararlos como no definidos:

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

Answer 3

documentos de la API de forma dinámica los idiomas mecanografiados pueden no ser muy significativos si no se escriben con cuidado, por lo tanto, no se sienta mal por ello, incluso el desarrollador más avezado puede tener dificultades para tratar de comprenderlos.

Acerca de los corchetes y tal, generalmente hay una sección de convenciones de código que debe explicar el uso exacto fuera de los ejemplos literales; aunque EBNF, Regex y Railroad Diagrams son casi omnipresentes, por lo que debe familiarizarse con ellos para comprender la mayoría de las anotaciones.

Answer 4

Hace un tiempo tuve la misma pregunta y alguien me indicó Extended Backus–Naur Form.

Tiene sentido porque la programación se puede utilizar para crear resultados potencialmente ilimitados. La documentación no puede mostrar un ejemplo para cada caso posible. Un buen ejemplo de uso común lo ayudo, pero una vez que puede leer la sintaxis subyacente, puede crear su propio código.