Вопрос по api, documentation – Как читать документацию по API для новичков? [закрыто]

88

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

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

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

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

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

myPath.fillPath(myNewColor)

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

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

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

Так,is there some mysterious document somewhere that tells people how to read API documentation? Почему так написано? Какие предварительные знания он предполагает у меня? Почему это так, и что я могу сделать, чтобы перестать задаваться вопросом об этом и "получить" это, так что я могу более счастливо читать и реализовать следующий API?

So why is API documentation written in such a way as to confuse perennial newbs / hackers / DIYers like myself?

Есть ли введение в справочный документ API, в котором описаны их синтаксические соглашения? Greg Hewgill
Полезным ресурсом является средство просмотра объектов, встроенное в IDE Extendscript (хит F1). Нажатие на объект покажет вам, какие свойства и методы у него есть. Также, если он использует другие объекты в качестве параметров, он (обычно) ссылается на них, чтобы вы могли видеть, какие свойства у них тоже есть. Это не идеально, но это помогает. pdizz
Для человека, который проголосовал за закрытие: я считаю, что этот вопрос имеет свои достоинства, и «проголосовал бы за то, чтобы не закрывать» если бы я мог. Это не тот вопрос, который я видел (или слышал) раньше, он затрагивает законную проблему, связанную с программированием, и я лично нашел бы ответ полезным, когда я учу людей вещам, связанным с программированием. David Wolever
Дерек: Я думаю, что вы пропустили одно из смелых предложений в оригинальном посте. Если вы в Google «читаете API-документацию», информация в первых 10 результатах говорит о таких вещах, как «абстрактный», «неполный», «запутанный» и т. Д., Что подтверждает смысл моего вопроса. dbonneville
Грег: Нет представления о продуктах Photoshop / Adobe. Все они следуют одному и тому же формату в 2 PDF-файлах на продукт Другие API, о которых я думаю, делают то же самое. Существует неявное знание, которого я во многих случаях не имею и, безусловно, хотел бы получить. dbonneville

Ваш Ответ

4   ответа
3

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

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

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

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

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

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

1

Расширенная спина - форма Наура.

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

76

So why is API documentation written in such a way as to confuse perennial newbs / hackers / DIYers like myself?

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

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

Is there some mysterious document somewhere that tells people how to read API documentation?

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

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

Underlined words are considered literals, and are typed just as they appear.

Square brackets ( [] ) around an argument indicate that the argument is optional.

Ellipses ... are used to show that the previous argument-prototype may be repeated.

An argument beginning with a minus sign - is often taken to mean some sort of flag argument even if it appears in a position where a file name could appear.

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

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

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

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

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

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 / программирования. Однако в каждом документе могут быть тонкие различия. Как опытный пользователь или разработчик, вы ДОЛЖНЫ иметь возможность читать и понимать документы / рамки / библиотеки, которые вы пытаетесь использовать.

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

Похожие вопросы