Як інтерпретувати параметри документації API документації?

Чи існує стандарт інтерпретації синтаксису функціональних інтерфейсів в документації API і якщо так, то як це визначено?

Ось приклад того, як змінити колір елемента, керівництво сценарієм JavaScript для Photoshop для функції "fillColor":

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

Яке значення дужок і чому в дужках є коми? Як це стосується наступних прикладів дзвінків?

myPath.fillPath(myNewColor)

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

То чому ж документація API написана таким чином, щоб заплутати багаторічних новичок / хакерів / DIYers, як я?

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

Як правило, тип людини, яка працює з API, матиме певний досвід розвитку або, принаймні, "споживач потужності". Ці типи користувачів звикли до таких конвенцій синтаксису, і для API документа більше сенсу слідувати, ніж намагатися створити нові.

Чи є десь таємничий документ, який розповідає людям, як читати документацію API?

Дійсно не існує стандартного, або RFC, суперсекретсинтаксдоку, що лежить навколо де завгодно, однак є ~ 30-річний файл для формату синхроситу UNIX man page, який широко використовується.

Деякі приклади цього (і відповіді на ваше запитання):

Підкреслені слова вважаються буквальними і вводяться так само, як вони з’являються.

Квадратні дужки ([]) навколо аргументу вказують, що аргумент необов’язковий.

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

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

Майже вся документація, що стосується програмування, використовує цей тип конвенції синтаксису, починаючи з Python , man man, сторінок 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 майже всюдисущі, тому вам слід ознайомитися з ними, щоб зрозуміти більшість позначень.

Дужки означають, що властивість не є обов'язковою. Будьте в курсі, що якщо ви хочете встановити якусь властивість у ранзі nTh, вам потрібно або оголосити властивості для провідного, або оголосити їх як невизначені:

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

У мене це питання було деякий час назад, і хтось вказав мені на розширену форму "Бекус-Наур" .

Це має сенс, оскільки програмування можна використовувати для створення потенційно необмежених результатів. Документація не може відображати приклад для кожного можливого випадку. Я корисний приклад загального використання Я корисний, але як тільки ви зможете прочитати основний синтаксис, ви зможете створити власний код.