Jak czytać dokumentację API dla newbs? [Zamknięte]
Czytam podręcznik skryptu JavaScript dla Photoshop, Illustrator i InDesign. Interfejs API jest naprawdę trudny do odczytania, ponieważ zakłada, że znam pewne skrócone konwencje. Problem nie ogranicza się do tego konkretnego przewodnika po skryptach. Mógłbym wymienić dziesiątki, które przedstawiają ten sam problem.
Kiedy czytam API jako kogoś, kto nie mieszka w kodzie 24 godziny na dobę, chcę coś sprawdzić i zobaczyć prosty przykład kodu w akcji w najbardziej podstawowej formie. Ale na początku nie jest łatwo to zrozumieć.
Oto przykład. Sprawdzam, jak zmienić kolor elementu przez JavaScript w Photoshopie. Przeszukuję więc plik PDF i znajduję „fillColor”. Znajduję to w dokumentach:
fillPath
([fillColor]
[, mode]
[, opacity]
[, preserveTransparency] [, feather]
[, wholePath] [, antiAlias])
Kiedy to czytam, na pierwszy rzut oka nie ma sensu. Dlaczego są nawiasy i skąd mam wiedzieć, że nie powinienem ich używać w implementacji? Dlaczego przecinki są w nawiasach? Wiem co to za kodpowinien wyglądam jak z próbki, którą znalazłem, która jest następująca:
myPath.fillPath(myNewColor)
Gdybym nie widział przykładu, NIGDY nie dowiedziałbym się z kodu API, że tak powinna wyglądać ta metoda po zaimplementowaniu. Ktoś inny wskazał, że rozszerzony przykład tej metody może wyglądać tak:
myPath.fillPath(mynewColor, {
mode: RGB,
opacity: .5
})
DOBRZE. Widzę, że mogę pominąć domyślne parametry opcjonalne. W porządku. Ale ponownie, nigdy nie odgadłbym tego z API.
Więc,Czy jest gdzieś jakiś tajemniczy dokument, który mówi ludziom, jak czytać dokumentację API? Dlaczego tak jest napisane? Jaką wcześniejszą wiedzę zakłada, że mam? Dlaczego tak jest i co mogę zrobić, aby przestać się nad tym zastanawiać i „zdobyć” to, aby lepiej czytać i implementować następne API?
Dlaczego więc dokumentacja API jest napisana w taki sposób, aby zmylić wieloletnich nowicjuszy / hakerów / majsterkowiczów takich jak ja?