Estou lendo o guia de script do JavaScript para Photoshop, Illustrator e InDesign. A API é realmente difícil de ler porque pressupõe que eu conheça certas convenções abreviadas. O problema não está limitado a este guia de script específico. Eu poderia listar dezenas que apresentam o mesmo problema.

Quando eu leio uma API como alguém que não vive no código 24 horas por dia, quero procurar algo e ver um exemplo simples do código em ação na forma mais básica. Mas muitas vezes não é fácil entender inicialmente.

Aqui está um exemplo. Eu estou procurando como alterar a cor de um item por JavaScript no Photoshop. Então eu pesquiso no PDF e encontro "fillColor". Eu acho isso nos documentos:

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

Quando leio isso, à primeira vista não faz sentido. Por que existem colchetes e como eu saberia que não deveria usá-los em uma implementação? Por que vírgulas estão entre colchetes? Eu sei o que o códigodevemos parece com uma amostra que encontrei, que é isto:

myPath.fillPath(myNewColor)

Se eu não tivesse visto o exemplo, eu NUNCA adivinharia o código da API que é como esse método deve ser quando implementado. Alguém apontou que um exemplo estendido para esse método poderia ser assim:

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

ESTÁ BEM. Eu vejo que posso deixar de fora os parâmetros opcionais implícitos. Bem. Mas, novamente, eu nunca teria adivinhado isso da API.

Assim,Existe algum documento misterioso em algum lugar que diz às pessoas como ler a documentação da API? Por que está escrito assim? Que conhecimento prévio assume que eu tenho? Por que é assim, e o que eu posso fazer para parar de pensar sobre isso e "conseguir", para que eu possa ler e implementar com mais alegria a próxima API?

Então, por que a documentação da API é escrita de forma a confundir newbs perenes / hackers / DIYers como eu?