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

Question

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

Estoy leyendo la guía de scripting JavaScript para Photoshop, Illustrator e InDesign. La API es muy difícil de leer porque asume que conozco ciertas convenciones taquigráficas. El problema no se limita 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 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. Así que busco el PDF y encuentro "fillColor". Encuentro esto en los documentos:

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

Cuando leo esto, a primera vista no tiene sentido. ¿Por qué hay corchetes y cómo sabría que no debo usarlos en una implementación? ¿Por qué hay comas entre paréntesis? Sé cómo debería ser el código de una muestra que encontré, que es esto:

myPath.fillPath(myNewColor)

Si no hubiera visto el ejemplo, NUNCA adivinaría por el código de la API que así es como debe verse este método cuando se implementa. Alguien más 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 dejar fuera los parámetros opcionales implícitos. Fino. Pero de nuevo, NUNCA habría adivinado esto de la API.

Entonces, ¿hay algún documento misterioso en algún lugar que le diga a la gente cómo leer la API ¿documentación? ¿por Qué está escrito así? ¿Qué conocimiento previo asume que tengo? ¿Por qué es así, y qué puedo hacer para dejar de preguntarme sobre ello y "conseguirlo", para que pueda leer más felizmente e implementar la próxima API?

Entonces, ¿por qué la documentación de la API está escrita de tal manera que confunda a los novatos / hackers / DIYers perennes como yo?

79

api documentation

Author: Peter O., 2012-06-07

Source

4 answers

Los documentos de API para lenguajes tipeados dinámicamente pueden no ser muy significativos si no se escriben con cuidado, así que no se sienta mal al respecto, incluso el desarrollador más experimentado puede tener dificultades para entenderlos.

Sobre los corchetes y demás, generalmente hay una sección de convenciones de código que debería explicar el uso exacto fuera de los ejemplos literales; aunque EBNF, Regex y Los diagramas de ferrocarril son casi omnipresentes, por lo que debe estar familiarizado con ellos para entiende la mayoría de las notaciones.

5

Author: fortran,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2013-01-16 15:08:44

Los corchetes significan que la propiedad es opcional. Sin embargo, tenga en cuenta que si desea establecer la propiedad soem en el enésimo rango, debe declarar las propiedades para el eading o declararlas como indefinidas:

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

3

Author: Loic Aigon,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2012-06-08 13:47:32

Tuve esta misma pregunta hace un tiempo y alguien me señaló Extended Backus–Naur Form.

Tiene sentido porque la programación se puede usar para crear resultados potencialmente ilimitados. La documentación no puede mostrar un ejemplo para todos los casos posibles. Un buen ejemplo de uso común I útil, pero una vez que se puede leer la sintaxis subyacente que son capaces de crear su propio código.

1

Author: StevenKW,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2015-01-04 18:38:31

score 70 · Accepted Answer

Entonces, ¿por qué la documentación de la API está escrita de tal manera que confunda a los novatos / hackers / DIYers perennes como yo?

Realmente no está destinado a ser escrito de esa manera. Estoy de acuerdo en que no parece haber facilidad de uso en todas las documentaciones de API. Sin embargo, hay una gran cantidad de cruces de las convenciones de sintaxis de estilo man más antiguas, a las convenciones de API/espacio de nombres modernas.

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

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

Realmente no hay un estándar, o RFC, supersekretsyntaxdoc por ahí, sin embargo, hay un archivo de ~30 años de antigüedad para UNIX formato synposis de la página de manual que está muy extendido utilizar.

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

Las palabras subrayadas se consideran literales y se escriben tal como aparecen.

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

Elipses ... se utilizan para mostrar que el argumento anterior-prototype puede repetirse.

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

Casi toda la documentación relacionada con la programación utiliza este tipo de convención de sintaxis, desde Python, páginas man , libs javascript ( Highcharts), etc.

Desglosar el ejemplo de la API de Adobe

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

Vemos que fillPath() (una función) toma argumentos opcionales fillColor, mode, opacity, preserveTransparency, feathe, wholePath o antiAlias. Al llamar a fillPath(), puede pasar de ninguno a todos esos parámetros. Las comas dentro de la opción [] significa que si este parámetro se usa además de otros, necesita la coma para separarlo. (El sentido común a veces, seguro, pero a veces algunos lenguajes como VB, explícitamente necesitan esas comas para delinear correctamente qué parámetro falta!). Dado que no se vinculó a la documentación (y no puedo encontrarla en La página de scripting de Adobe), realmente no hay una manera de saber qué formato está esperando la API de Adobe. Sin embargo, debe haber una explicación en la parte superior de la mayor parte de la documentación que explica las convenciones utilizadas dentro.

Por lo tanto, esta función probablemente podría usarse 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

De nuevo, generalmente hay algunos estándares en todas las documentaciones relacionadas con 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 está intentando usar.