Как читать документацию по API для новичков? [закрыто]
Я читаю руководство по написанию сценариев 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?
Ответы на вопрос(4)
что свойство является необязательным. Имейте в виду, что если вы хотите установить свойство soem на ранг nTh, вы должны либо объявить свойства для уходящего, либо объявить их как неопределенные:
fillPath() //good
fillPath ( someFillColor ) //good
fillPath ( someFillColor, mode ) //good
fillPath ( undefined, mode ) //good
fillPath ( mode ) //bad
fillPath ( undefined ) //really bad
fillPath (mode) может быть в порядке. Если необязательный аргумент предшествует необязательному, это часто означает, что функция достаточно умна, чтобы определить, был ли задан необязательный аргумент или нет (например, глядя на его тип)ь значимыми, если их не писать тщательно, так что не расстраивайтесь из-за этого, даже самым опытным разработчикам может быть трудно понять их.
Что касается скобок и тому подобного, то обычно есть раздел условных обозначений кода, который должен объяснить точное использование вне буквальных примеров; хотяEBNF, Regex а такжеЖелезнодорожные схемы почти повсеместно, поэтому вы должны быть знакомы с ними, чтобы понять большинство обозначений.
Расширенная спина - форма Наура.
Это имеет смысл, потому что программирование может использоваться для создания потенциально безграничных результатов. Документация не может отображать пример для каждого возможного случая. Хороший пример общего использования, который мне полезен, но как только вы сможете прочитать основной синтаксис, вы сможете создать свой собственный код.
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 / программирования. Однако в каждом документе могут быть тонкие различия. Как опытный пользователь или разработчик, вы ДОЛЖНЫ иметь возможность читать и понимать документы / рамки / библиотеки, которые вы пытаетесь использовать.