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


105

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

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

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

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

myPath.fillPath(myNewColor)

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

4
Есть ли введение в справочный документ API, в котором описаны их синтаксические соглашения?
Грег Хьюгилл

35
Для человека, проголосовавшего за закрытие: я считаю, что этот вопрос заслуживает внимания, и я бы "проголосовал за закрытие", если бы мог. Это не вопрос, который я видел (или слышал) раньше, он касается законной проблемы, связанной с программированием, и я лично нашел бы ответ полезным, когда учу людей вещам, связанным с программированием.
Дэвид Волевер 07

4
Дерек: Я думаю, вы пропустили одно из смелых предложений в исходном посте. Если вы погуглите «как читать документацию по API», информация в первых 10 результатах будет содержать такие вещи, как «абстрактный», «неполный», «сбивающий с толку» и т. Д., Тем самым усиливая суть моего вопроса.
dbonneville

2
Грег: Нет никаких представлений о продуктах Photoshop / Adobe. Все они имеют один и тот же формат в двух PDF-файлах для каждого продукта. Другие API, о которых я думаю, делают то же самое. Есть неявное знание, которого я во многих случаях не имею и, безусловно, хотел бы знать.
dbonneville

1
Полезный ресурс - это средство просмотра объектов, встроенное в Extendscript IDE (нажмите F1). Щелчок по объекту покажет вам, какие свойства и методы у него есть. Также, если он использует другие объекты в качестве параметров, он (обычно) ссылается на них, чтобы вы также могли видеть, какие свойства они имеют. Это не идеально, но помогает.
pdizz

Ответы:


93

Так почему же документация по 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 / программированию, есть некоторые стандарты. Однако в каждом документе могут быть небольшие различия. Как опытный пользователь или разработчик, ожидается, что вы сможете читать и понимать документы / фреймворки / библиотеки, которые вы пытаетесь использовать.


5
Ссылка в формате синопсиса справочной страницы UNIX мертва - у кого-нибудь есть ссылка на замену? Обновление @PenguinCoder: основано на [ unix.stackexchange.com/questions/17833/… (Unix Stack Exchange), оно частично основано на [ en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_Form (EBNF)
steviejay

Существует архивная копия из страницы человека synposis формата
CodeManX

6

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

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


3

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

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

2
fillPath (mode)может быть нормально. Если необязательный аргумент предшествует необязательному, это часто означает, что функция достаточно умна, чтобы определить, был ли указан необязательный аргумент или нет (например, по его типу)
ThiefMaster 08

1
ММмм, это возможно, но я предпочитаю полагаться на что-то сильное, чем на то, что сценарий может сделать для меня: D
Лоик Эйгон

1

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

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

Используя наш сайт, вы подтверждаете, что прочитали и поняли нашу Политику в отношении файлов cookie и Политику конфиденциальности.
Licensed under cc by-sa 3.0 with attribution required.