¿Cómo interpretar los parámetros de función en la documentación de software y lenguaje?
¿Existe un estándar para interpretar la sintaxis de las interfaces de funciones en la documentación de la 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 JavaScript para Photoshop para la función "fillColor":
fillPath
([fillColor]
[, mode]
[, opacity]
[, preserveTransparency] [, feather]
[, wholePath] [, antiAlias])
¿Cuál es el significado de los paréntesis y por qué hay comas entre paréntesis? ¿Cómo se relaciona esto con las siguientes llamadas de ejemplo?
myPath.fillPath(myNewColor)
myPath.fillPath(mynewColor, {
mode: RGB,
opacity: .5
})
Entonces, ¿por qué la documentación API está escrita de tal manera que confunda a los novatos, hackers y aficionados al bricolaje como yo?
Realmente no debe escribirse de esa manera. Estoy de acuerdo en que parece que no hay facilidad de uso en la documentación de API. Sin embargo, hay muchos cruces entre manlas convenciones de sintaxis de estilo antiguo y las convenciones modernas de API/espacio de nombres.
Por lo general, el tipo de persona que trabaja con API tendrá cierta experiencia en desarrollo o al menos un "usuario avanzado". Este tipo de usuarios están acostumbrados a este tipo de convenciones de sintaxis y tiene más sentido seguir el documento API que intentar 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 existe un supersekretsyntaxdoc estándar, o RFC, por ningún lado; sin embargo, hay un archivo de aproximadamente 30 años de antigüedad para el formato de síntesis de páginas de manual de UNIX que es de uso generalizado.
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.
Las elipses... se utilizan para mostrar que el prototipo de argumento anterior puede repetirse.
Un argumento que comienza con un signo menos a menudo se considera como 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 a fillPath(), puede pasarle desde ninguno hasta todos esos parámetros. Las comas dentro del opcional []significan que si este parámetro se usa además de otros, necesitará la coma para separarlo. (Seguro que a veces tiene sentido común, pero a veces algunos lenguajes como VB necesitan explícitamente esas comas para delinear correctamente qué parámetro falta). Dado que no vinculó 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 de la documentación que explique las convenciones utilizadas 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 existen algunos estándares en toda la documentación relacionada con API/programación. Sin embargo, en cada documento puede haber diferencias sutiles. Como usuario avanzado o desarrollador, SE espera que usted pueda leer y comprender los documentos/marcos/bibliotecas que intenta utilizar.
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.
En cuanto a 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 EBNF , Regex y Railroad Diagrams son casi omnipresentes, por lo que debes estar familiarizado con ellos para comprender la mayoría de las notaciones.
Los corchetes significan que la propiedad es opcional. Sin embargo, tenga en cuenta que si desea establecer alguna propiedad en el rango nTh, debe declarar propiedades para la principal o declararlas como indefinidas:
fillPath() //good
fillPath ( someFillColor ) //good
fillPath ( someFillColor, mode ) //good
fillPath ( undefined, mode ) //good
fillPath ( mode ) //bad
fillPath ( undefined ) //really bad
Tuve la misma pregunta hace un tiempo y alguien me señaló 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 puedas leer la sintaxis subyacente, podrás crear tu propio código.
