Jak interpretować parametry funkcji dokumentacji API?


104

Czy istnieje standard interpretacji składni interfejsów funkcji w dokumentacji API, a jeśli tak, to w jaki sposób jest on definiowany?

Oto przykład zmiany koloru elementu w przewodniku skryptów JavaScript dla programu Photoshop dla funkcji „fillColor”:

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

Jakie jest znaczenie nawiasów i dlaczego w nawiasach są przecinki? Jak to się ma do następujących przykładowych wywołań?

myPath.fillPath(myNewColor)

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

4
Czy istnieje wprowadzenie do dokumentu referencyjnego interfejsu API, które opisuje ich konwencje składniowe?
Greg Hewgill

35
Dla osoby, która głosowała za zamknięciem: uważam, że to pytanie jest uzasadnione i gdybym mógł, „głosowałbym za niezamknięciem”. To nie jest pytanie, które wcześniej widziałem (lub słyszałem), dotyczy ono uzasadnionego problemu związanego z programowaniem i osobiście uznałbym odpowiedź za przydatną, kiedy uczę ludzi programowania.
David Wolever,

4
Derek: Myślę, że przegapiłeś jedno z odważnych zdań w oryginalnym poście. Jeśli wyszukasz w Google „jak czytać dokumentację API”, informacje w pierwszych 10 wynikach będą zawierać słowa „abstrakcyjne”, „niekompletne”, „zagmatwane” itp., Co wzmacnia sedno mojego pytania.
dbonneville

2
Greg: Nie ma żadnych wstępów do produktów Photoshop / Adobe. Wszystkie mają ten sam format w 2 plikach PDF na produkt. Inne interfejsy API, o których myślę, robią to samo. Istnieje ukryta wiedza, której w wielu przypadkach nie mam i na pewno chciałbym.
dbonneville

1
Przydatnym zasobem jest przeglądarka obiektów wbudowana w Extendscript IDE (wciśnij F1). Kliknięcie obiektu pokaże Ci, jakie ma właściwości i metody. Również jeśli używa innych obiektów jako parametrów, (zwykle) łączy się z nimi, abyś mógł zobaczyć, jakie mają właściwości. Nie jest doskonały, ale pomaga.
pdizz

Odpowiedzi:


93

Dlaczego więc dokumentacja API jest napisana w taki sposób, aby zmylić odwiecznych nowicjuszy / hakerów / majsterkowiczów, takich jak ja?

To naprawdę nie ma być napisane w ten sposób. Zgadzam się, że nie ma łatwości użycia w całej dokumentacji API. Istnieje jednak wiele przejść ze starszych mankonwencji składniowych do nowoczesnych konwencji API / przestrzeni nazw.

Zazwyczaj osoba, która pracuje z API, ma pewne doświadczenie w programowaniu lub przynajmniej ma „zaawansowanego użytkownika”. Tacy użytkownicy są przyzwyczajeni do takich konwencji składniowych i bardziej sensowne jest przestrzeganie dokumentu API niż próba tworzenia nowych.

Czy jest gdzieś jakiś tajemniczy dokument, który mówi ludziom, jak czytać dokumentację API?

Naprawdę nie ma standardowego, lub RFC, supersekretsyntaxdoc, który można znaleźć wszędzie, jednak istnieje ~ 30-letni plik formatu synposis strony podręcznika systemu UNIX, który jest szeroko stosowany.

Oto kilka przykładów (i odpowiedzi na Twoje pytanie):

Podkreślone słowa są traktowane jako dosłowne i wpisywane tak, jak się pojawiają.

Nawiasy kwadratowe ([]) wokół argumentu wskazują, że argument jest opcjonalny.

Wielokropki ... służą do pokazania, że ​​poprzedni prototyp argumentu może się powtórzyć.

Argument rozpoczynający się od znaku minus - jest często traktowany jako oznaczający jakiś rodzaj argumentu flagowego, nawet jeśli pojawia się w miejscu, w którym może pojawić się nazwa pliku.

Prawie cała dokumentacja związana z programowaniem używa tego typu konwencji składni, począwszy od języka Python , stron podręcznika systemowego , bibliotek javascript ( Highcharts ) itp.


Przedstawienie przykładu z Adobe API

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

Widzimy, że fillPath()(funkcja) przyjmuje opcjonalne argumenty fillColor, mode, opacity, preserveTransparency, feathe, wholePathlub antiAlias. Wywołując fillPath(), możesz przekazać do niego dowolne z tych parametrów do wszystkich. Przecinki w polu opcjonalnym []oznaczają, że jeśli ten parametr jest używany oprócz innych, potrzebujesz przecinka, aby go oddzielić. (Czasami zdrowy rozsądek, na pewno, ale czasami niektóre języki, takie jak VB, wyraźnie potrzebują tych przecinków, aby poprawnie określić, którego parametru brakuje!). Ponieważ nie podałeś linku do dokumentacji (i nie mogę jej znaleźć na stronie skryptów Adobe ), naprawdę nie ma sposobu, aby dowiedzieć się, jakiego formatu oczekuje interfejs API Adobe. Jednak na górze większości dokumentacji powinno znajdować się wyjaśnienie wyjaśniające stosowane w nich konwencje.

Tak więc ta funkcja może być prawdopodobnie używana na wiele sposobów:

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

Ponownie, zazwyczaj we wszystkich dokumentach dotyczących API / programowania istnieją pewne standardy. Jednak w każdym dokumencie mogą występować subtelne różnice. Jako użytkownik zaawansowany lub programista Oczekuje się, że będziesz w stanie czytać i rozumieć dokumenty / struktury / biblioteki, których próbujesz użyć.


5
Link do formatu streszczenia strony podręcznika systemu UNIX jest martwy - ktoś ma łącze zastępcze? Aktualizacja @PenguinCoder: Oparta na [ unix.stackexchange.com/questions/17833/… (Unix Stack Exchange), luźno oparta na [ en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_Form (EBNF)
steviejay

Jest zarchiwizowany copy of strona man synposis formacie
CodeManX

6

Dokumentacja API dla języków dynamicznie typowanych może nie być zbyt znacząca, jeśli nie zostanie napisana starannie, więc nie przejmuj się tym, nawet najbardziej doświadczony programista może mieć trudności z ich zrozumieniem.

Jeśli chodzi o nawiasy i tym podobne, zwykle znajduje się sekcja dotycząca konwencji kodu, która powinna wyjaśniać dokładne użycie poza przykładami dosłownymi; chociaż schematy EBNF , Regex i Railroad są prawie wszechobecne, więc powinieneś się z nimi zapoznać, aby zrozumieć większość notacji.


3

Nawiasy oznaczają, że właściwość jest opcjonalna. Pamiętaj jednak, że jeśli chcesz ustawić jakąś właściwość na rangę nTh, musisz albo zadeklarować właściwości dla wiodącej wartości, albo zadeklarować je jako niezdefiniowane:

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

2
fillPath (mode)może być w porządku. Jeśli opcjonalny argument występuje przed
nieopcjonalnym

1
MMmm, cóż, to możliwe, ale wolę polegać na czymś mocnym, niż na tym, co scenariusz mógłby dla mnie zrobić: D
Loic Aigon,

1

Miałem to samo pytanie jakiś czas temu i ktoś wskazał mi Rozszerzoną Formę Backusa-Naura .

Ma to sens, ponieważ programowanie może służyć do tworzenia potencjalnie nieograniczonych wyników. Dokumentacja nie może zawierać przykładu dla każdego możliwego przypadku. Dobry przykład powszechnego użycia. Pomogłem, ale kiedy już przeczytasz podstawową składnię, będziesz w stanie stworzyć własny kod.

Korzystając z naszej strony potwierdzasz, że przeczytałeś(-aś) i rozumiesz nasze zasady używania plików cookie i zasady ochrony prywatności.
Licensed under cc by-sa 3.0 with attribution required.