Jak interpretować parametry funkcji dokumentacji API?

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
})

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ć.

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.

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

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.