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

Estoy leyendo la guía de scripts de JavaScript para Photoshop, Illustrator e InDesign. La API es realmente difícil de leer porque asume que conozco ciertas convenciones abreviadas. 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 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. Busco cómo cambiar el color de un elemento mediante 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? Yo se cual es el codigodebería Parezco a partir de una muestra que encontré, que es esta:

myPath.fillPath(myNewColor)

Si no hubiera visto el ejemplo, NUNCA lo haría con el código API, así es como debería verse este método cuando se implemente. Alguien más señaló que un ejemplo extendido para este método podría verse así:

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

DE ACUERDO. Veo que puedo dejar de lado los parámetros opcionales implícitos. Multa. Pero una vez más, NUNCA lo habría adivinado desde la API.

Asi que,¿Hay algún documento misterioso en algún lugar que le diga a la gente cómo leer la documentación de la API? ¿Por qué está escrito así? ¿Qué conocimientos previos supone que tengo? ¿Por qué es así, y qué puedo hacer para dejar de preguntarme y "obtener", para que pueda leer e implementar la próxima API con más alegría?

Entonces, ¿por qué la documentación de la API está escrita de tal manera que confunde a los newbs / hackers / DIYers perennes como a mí?

Respuestas a la pregunta(4)

Su respuesta a la pregunta