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?

questionAnswers(4)

yourAnswerToTheQuestion