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

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

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

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

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

myPath.fillPath(myNewColor)

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

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

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

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

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

На самом деле нет никаких стандартных или RFC, суперсекретсинтаксdoc, лежащих где-либо, однако есть файл примерно 30-летней давности для формата синпозиций страниц руководства UNIX, который широко используется.

Вот несколько примеров этого (и ответа на ваш вопрос):

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

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

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

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

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

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

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

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

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

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

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

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

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

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