Как интерпретировать параметры функций документации API?

Существует ли стандарт для интерпретации синтаксиса интерфейсов функций в документации API, и если да, то как он определяется?

Вот пример того, как изменить цвет элемента руководство по сценариям JavaScript для Photoshop для функции "fillColor":

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

Каково значение скобок и почему в скобках стоят запятые? Как это связано со следующими примерами вызовов?

myPath.fillPath(myNewColor)

myPath.fillPath(mynewColor, {
    mode: RGB,
    opacity: .5
})
Konrad Höffner
Редактировал вопрос 19-го июня 2019 в 10:03
Программирование
api documentation
7-го июня 2012 в 3:59
21 просмотров
Комментарии к вопросу (6)
Решение

**Почему же документация по API написана таким образом, чтобы запутать таких новичков, хакеров и DIYеров, как я?

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

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

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

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

Примерами этого (и ответами на ваш вопрос) могут быть:

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

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

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

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

Почти вся документация по программированию использует этот тип синтаксического соглашения, начиная с Python, man pages, javascript libs (Highcharts) и т.д.

Разбор примера с Adobe API

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

Мы видим, что fillPath() (функция) принимает необязательные аргументы fillColor, mode, opacity, preserveTransparency, feathe, wholePath или antiAlias. Вызывая fillPath(), вы можете передать ей любой из этих параметров, от одного до всех. Запятая внутри необязательного [] означает, что если этот параметр используется в дополнение к другим, то запятая нужна для их разделения. (Здравый смысл иногда, конечно, но иногда некоторые языки, такие как VB, явно нуждаются в этих запятых, чтобы правильно определить, какой параметр отсутствует!). Поскольку вы не дали ссылку на документацию (и я не могу найти ее на Adobe's scripting page), действительно нет способа узнать, какой формат ожидает 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/программированию. Однако в каждом документе могут быть тонкие различия. Как опытный пользователь или разработчик, вы ДОЛЖНЫ уметь читать и понимать документы/фреймворки/библиотеки, которые вы пытаетесь использовать.

Комментарии (1)

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

Что касается скобок и тому подобного, обычно есть раздел "Соглашения по коду", который должен объяснить точное использование вне буквальных примеров; хотя EBNF, Regex и Railroad Diagrams почти вездесущи, поэтому вы должны быть знакомы с ними, чтобы понять большинство обозначений.

Комментарии (0)

Скобки означают, что свойство является необязательным. Однако имейте в виду, что если вы хотите установить такое свойство на nTh ранге, вы должны либо объявить свойства для предыдущего ранга, либо объявить их как неопределенные:

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

Jamiec
Редактировал ответ 8-го июня 2012 в 1:47
Комментарии (2)

У меня был этот же вопрос некоторое время назад и кто-то указал мне на расширенная форма Бэкуса–Наура.

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

Комментарии (0)