Я читаю руководство по написанию сценариев JavaScript для Photoshop, Illustrator и InDesign. API действительно трудно читать, потому что он предполагает, что я знаю некоторые условные обозначения. Проблема не ограничивается этим конкретным руководством по написанию сценариев. Я мог бы перечислить десятки, которые представляют ту же проблему.

Когда я читаю API как человека, который не живет в коде 24 часа в сутки, я хочу что-то посмотреть и увидеть простой пример кода в действии в самой простой форме. Но часто поначалу нелегко понять это.

Вот пример. Я смотрю, как изменить цвет элемента с помощью JavaScript в Photoshop. Поэтому я ищу в PDF и нахожу «fillColor». Я нахожу это в документах:

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

Когда я читаю это, это на первый взгляд не имеет смысла. Почему есть скобки и откуда я знаю, что я не должен использовать их в реализации? Почему запятые в скобках? Я знаю что за кодshould похож на образец, который я нашел, а именно:

myPath.fillPath(myNewColor)

Если бы я не видел пример, я НИКОГДА не угадаю из кода API, как этот метод должен выглядеть при реализации. Кто-то еще указал, что расширенный пример для этого метода может выглядеть следующим образом:

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

ХОРОШО. Я вижу, что могу пропустить подразумеваемые необязательные параметры. Хорошо. Но опять же, я НИКОГДА не догадался бы об этом по API.

Так,is there some mysterious document somewhere that tells people how to read API documentation? Почему так написано? Какие предварительные знания он предполагает у меня? Почему это так, и что я могу сделать, чтобы перестать задаваться вопросом об этом и "получить" это, так что я могу более счастливо читать и реализовать следующий API?

So why is API documentation written in such a way as to confuse perennial newbs / hackers / DIYers like myself?