Как читать документацию API для newbs? [закрытый]

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

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

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

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

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

myPath.fillPath(myNewColor)

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

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

ОК. Я вижу, что могу опустить подразумеваемые необязательные параметры. Штраф. Но опять же, я никогда бы не догадался об этом из API.

и есть какой-то таинственный документ где-то, что говорит людям, как читать документацию по API? почему так написано? Какие предварительные знания он предполагает, что у меня есть? Почему это так, и что я могу сделать, чтобы перестать задаваться этим вопросом и "получить" его, чтобы я мог более счастливо читать и реализовывать следующий API?

так почему же API документация написана таким образом, чтобы запутать многолетних newbs / хакеров / DIYers, как я?

4 79
api documentation

4 ответа:

так почему же документация API написана таким образом, чтобы запутать многолетних newbs / хакеров / DIYers, таких как я?

это действительно не должно быть написано таким образом. Я соглашусь, что, похоже, нет простоты использования в документах API. Тем не менее, есть много крестов от старых man соглашения синтаксиса стиля, к современным соглашениям API / пространства имен.

как правило, тип человека, который работает с API, будет иметь некоторый фон в разработка или, по крайней мере, "опытный пользователь". Эти типы пользователей используются для таких синтаксических соглашений, и для документа API имеет больше смысла следовать, чем пытаться создавать новые.

есть ли какой-то таинственный документ, который говорит людям, как читать документацию API?

там действительно нет стандарта, или RFC, supersekretsyntaxdoc лежа вокруг в любом месте, однако есть ~30-летний файл для UNIX человек synposis страницы формат который широко используется.

некоторые примеры этого (и отвечая на ваш вопрос) будет составлять :

Подчеркнутые слова считаются литералами, и вводятся так же, как они появляются.

квадратные скобки ([]) вокруг аргумента указывают, что аргумент является необязательным.

эллипсов ... используются, чтобы показать, что предыдущий аргумент-прототип может быть повторен.

аргумент, начинающийся с минуса знак-часто используется для обозначения какого-то аргумента флага, даже если он появляется в позиции, где может появиться имя файла.

почти вся документация, связанная с программированием, использует этот тип синтаксического соглашения, начиная с Python,страницы, библиотеками JavaScript (Highcharts) и т. д.

разбивка вашего примера из Adobe API

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

мы видим, что fillPath() (функция) принимает необязательный аргументы fillColor, mode, opacity, preserveTransparency, feathe, wholePath или antiAlias. Звоню fillPath(), вы можете передать куда угодно от none, ко всем, из этих параметров к нему. Запятые внутри необязательного [] означает, что если этот параметр используется в дополнение к другим, вы нужны запятая, чтобы отделить его. (Здравый смысл иногда, конечно, но иногда некоторые языки, такие как VB, явно нуждаются в этих запятых, чтобы правильно определить, какой параметр отсутствует!). Поскольку вы не ссылались на документацию (и я не могу найти ее на Adobe страница скрипта) на самом деле нет способа узнать, какой формат ожидает Adobe API. Однако, должно быть объяснение в верхней части большинство документация, объясняющая соглашения, используемые внутри.

таким образом, эта функция, вероятно, может быть использована многими способами :

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

опять же, обычно существуют некоторые стандарты во всех документах, касающихся API/программирования. Однако в каждом документе могут быть тонкие различия. Как опытный пользователь, или разработчик, вы должны быть в состоянии читать и понимать документы/фреймворки/библиотеки, которые вы пытаетесь использовать.

70

API-документы для динамически типизированных языков могут быть не очень значимыми, если они не написаны тщательно, поэтому не слишком плохо об этом, даже самый опытный разработчик может иметь трудное время, пытаясь понять их.

о скобках и т. д. Обычно существует раздел соглашений о коде, который должен объяснить точное использование вне буквальных примеров; хотя EBNF,выражение и Железной Дороги-Схемы почти повсеместно, так что вы должны быть знаком с ними, чтобы понять большинство обозначений.

5

скобки означают, что свойство является необязательным. Однако имейте в виду, что если вы хотите установить свойство soem в N-м ранге, вам нужно либо объявить свойства для eading one, либо объявить их как неопределенные :

fillPath() //good
fillPath ( someFillColor ) //good
fillPath ( someFillColor, mode ) //good
fillPath ( undefined, mode ) //good
fillPath ( mode ) //bad
fillPath ( undefined ) //really bad

Loic http://www.loicaigon.com

3

У меня был этот же вопрос некоторое время назад и кто-то указал мне на Расширенная Форма Backus-Naur.

Это имеет смысл, потому что программирование может быть использовано для создания потенциально неограниченных результатов. Документация не может отображать пример для каждого возможного случая. Хороший пример общего использования я полезно, но как только вы можете прочитать базовый синтаксис вы можете создать свой собственный код.

1