¿Cómo interpretar los parámetros de la función de documentación de la API?


103

¿Existe un estándar para interpretar la sintaxis de las interfaces de función en la documentación de API y, en caso afirmativo, cómo se define?

Aquí hay un ejemplo sobre cómo cambiar el color de un elemento en la guía de secuencias de comandos de JavaScript para Photoshop para la función "fillColor":

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

¿Cuál es el significado de los corchetes y por qué hay comas entre corchetes? ¿Cómo se relaciona esto con las siguientes llamadas de ejemplo?

myPath.fillPath(myNewColor)

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

4
¿Existe una introducción al documento de referencia de API que describa sus convenciones sintácticas?
Greg Hewgill

35
Para la persona que votó para cerrar: Creo que esta pregunta tiene mérito, y "votaría para no cerrar" si pudiera. No es una pregunta que haya visto (o escuchado) antes, aborda un problema legítimo relacionado con la programación y, personalmente, la respuesta me resultaría útil cuando le enseño a la gente cosas relacionadas con la programación.
David Wolever

4
Derek: Creo que te perdiste una de las oraciones en negrita de la publicación original. Si buscas en Google "cómo leer la documentación de la API", la información en los primeros 10 resultados dice cosas como "abstracto", "incompleto", "confuso", etc., lo que refuerza el punto de mi pregunta.
dbonneville

2
Greg: No hay presentaciones de los productos de Photoshop / Adobe. Todos siguen el mismo formato en 2 PDF por producto. Las otras API en las que estoy pensando hacen lo mismo. Hay un conocimiento implícito que en muchos casos no tengo y que sin duda me gustaría.
dbonneville

1
Un recurso útil es el visor de objetos integrado en Extendscript IDE (presione F1). Al hacer clic en un objeto, verá qué propiedades y métodos tiene. Además, si usa otros objetos como parámetros, (generalmente) se vincula a ellos para que pueda ver qué propiedades tienen también. No es perfecto pero ayuda.
pdizz

Respuestas:


92

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

Realmente no está destinado a estar escrito de esa manera. Estoy de acuerdo en que parece no haber facilidad de uso en todas las documentaciones de API. Sin embargo, hay mucho cruce de las manconvenciones de sintaxis de estilo más antiguas a las convenciones modernas de API / espacio de nombres.

Por lo general, el tipo de persona que trabaja con API tendrá alguna experiencia en desarrollo o al menos un 'usuario avanzado'. Estos tipos de usuarios están acostumbrados a tales convenciones de sintaxis y tiene más sentido seguir el documento API que intentar crear 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 un supersekretsyntaxdoc estándar, o RFC, por ahí, sin embargo, hay un archivo de ~ 30 años para el formato de síntesis de página de manual de UNIX que es de uso generalizado.

Algunos ejemplos de esto (y responder 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-prototipo anterior puede repetirse.

Un argumento que comienza con un signo menos, a menudo se considera que significa 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 de manual , bibliotecas de JavaScript ( Highcharts ), etc.


Desglosando su 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, wholePatho antiAlias. Al llamar fillPath(), podría pasar desde 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. (El sentido común a veces, seguro, pero a veces algunos lenguajes como VB, ¡necesitan explícitamente esas comas para delinear correctamente qué parámetro falta!). Dado que no enlazó a la documentación (y no puedo encontrarla en la página de secuencias de comandos de Adobe ), realmente no hay forma de saber qué formato espera la API de Adobe. Sin embargo, debería haber una explicación en la parte superior de la mayoría documentación que explique las convenciones que se utilizan en ella.

Entonces, 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

Nuevamente, generalmente hay algunos estándares en toda la documentación relacionada 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 utilizar.


5
El enlace del formato de sinopsis de la página de manual de UNIX está muerto. ¿Alguien tiene un enlace de reemplazo? Actualización de @PenguinCoder: Basado en [ unix.stackexchange.com/questions/17833/… (Unix Stack Exchange), se basa libremente en [ en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_Form (EBNF)
steviejay

Hay una copia archivada del formato de síntesis de la página del manual
CodeManX

5

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

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


3

Los corchetes significan que la propiedad es opcional. Sin embargo, tenga en cuenta que si desea establecer alguna propiedad en el n-ésimo rango, debe declarar propiedades para el líder o declararlas como indefinidas:

fillPath() //good
fillPath ( someFillColor ) //good
fillPath ( someFillColor, mode ) //good
fillPath ( undefined, mode ) //good
fillPath ( mode ) //bad
fillPath ( undefined ) //really bad

2
fillPath (mode)podría estar bien. Si un argumento opcional viene antes que uno no opcional, a menudo significa que la función es lo suficientemente inteligente como para detectar si el argumento opcional se proporcionó o no (por ejemplo, mirando su tipo)
ThiefMaster

1
Mmmm bueno, eso es posible, pero prefiero confiar en algo fuerte que en algo que el guión pueda hacer por mí: D
Loic Aigon

1

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

Tiene sentido porque la programación se puede utilizar 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 es útil, pero una vez que puede leer la sintaxis subyacente, puede crear su propio código.

Al usar nuestro sitio, usted reconoce que ha leído y comprende nuestra Política de Cookies y Política de Privacidad.
Licensed under cc by-sa 3.0 with attribution required.