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 man
convenciones 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, wholePath
o 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.