Как читать документацию по API для новичков?

68

Я читаю руководство по сценариям 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
})

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

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

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

  • 4
    Есть ли введение в справочный документ API, в котором описаны их синтаксические соглашения?
  • 30
    Для человека, который проголосовал за закрытие: я считаю, что этот вопрос имеет свои достоинства, и я бы «проголосовал за то, чтобы не закрывать», если бы мог. Это не тот вопрос, который я видел (или слышал), задаваемый ранее, он касается законной проблемы, связанной с программированием, и я лично нашел бы ответ полезным, когда я учу людей вещам, связанным с программированием.
Показать ещё 4 комментария
Теги:
documentation

4 ответа

59
Лучший ответ

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

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

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

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

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

Некоторые примеры этого (и ответа на ваш вопрос):

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

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

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

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

Почти вся документация, связанная с программированием, использует этот тип соглашения о синтаксисе, от 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), действительно не существует способа узнать, какой формат ожидается 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

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

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

Поделиться
3

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

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

Лоик http://www.loicaigon.com

Поделиться
  • 2
    fillPath (mode) может быть в порядке. Если необязательный аргумент предшествует не необязательному, это часто означает, что функция достаточно умна, чтобы определить, был ли задан необязательный аргумент или нет (например, просматривая его тип)
  • 1
    Ммммм, это возможно, но я предпочитаю полагаться на что-то сильное, чем то, что сценарий может сделать для меня: D
1

У меня был такой же вопрос некоторое время назад, и кто-то указал мне на Extended Backus-Naur Form.

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

Поделиться

Ещё вопросы

Сообщество Overcoder
Наверх
Меню