Come interpretare i parametri della funzione di documentazione API?

Esiste uno standard per interpretare la sintassi delle interfacce delle funzioni nelle documentazioni API e, in caso affermativo, come viene definita?

Di seguito è riportato un esempio su come modificare il colore di un elemento nella guida allo scripting JavaScript per Photoshop per la funzione "fillColor":

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

Qual è il significato delle parentesi e perché ci sono virgole tra parentesi? In che modo questo si collega alle seguenti chiamate di esempio?

myPath.fillPath(myNewColor)

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

Allora perché la documentazione API è scritta in modo tale da confondere i neofiti perenni / hacker / fai-da-te come me?

Non è davvero pensato per essere scritto in questo modo. Sono d'accordo che non sembra esserci facilità d'uso nelle documentazioni API. Tuttavia, c'è molto passaggio dalle manconvenzioni di sintassi di vecchio stile, alle moderne convenzioni API / spazio dei nomi.

In genere, il tipo di persona che lavora con API, avrà un background in fase di sviluppo o almeno un "utente esperto". Questi tipi di utenti sono abituati a tali convenzioni di sintassi e ha più senso seguire il documento API piuttosto che provare a crearne di nuovi.

C'è qualche documento misterioso da qualche parte che dice alle persone come leggere la documentazione API?

Non esiste davvero uno standard, o RFC, supersekretsyntaxdoc in giro da nessuna parte, tuttavia esiste un file di circa 30 anni per il formato di sinposi delle pagine di manuale di UNIX che è ampiamente utilizzato.

Alcuni esempi di questo (e rispondere alla tua domanda) potrebbero essere:

Le parole sottolineate sono considerate letterali e vengono digitate esattamente come appaiono.

Le parentesi quadre ([]) attorno a un argomento indicano che l'argomento è facoltativo.

Le ellissi ... sono usate per mostrare che il precedente argomento-prototipo può essere ripetuto.

Un argomento che inizia con un segno meno - viene spesso interpretato come una sorta di argomento flag anche se appare in una posizione in cui potrebbe apparire un nome di file.

Quasi tutta la documentazione relativa alla programmazione utilizza questo tipo di convenzione di sintassi, da Python , pagine man , librerie javascript ( Highcharts ), ecc.

Analizzando il tuo esempio dall'API di Adobe

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

Vediamo che fillPath()(una funzione) accetta argomenti opzionali fillColor, mode, opacity, preserveTransparency, feathe, wholePatho antiAlias. Chiamando fillPath(), potresti passare ovunque da nessuno, a tutti, di quei parametri ad esso. Le virgole all'interno dell'opzionale []significano che se questo parametro viene utilizzato in aggiunta ad altri, è necessaria la virgola per separarlo. (Il buon senso a volte, di sicuro, ma a volte alcuni linguaggi come VB, necessitano esplicitamente di quelle virgole per delineare correttamente quale parametro manca!). Dato che non hai inserito il link alla documentazione (e non riesco a trovarlo nella pagina di scripting di Adobe ), non c'è davvero un modo per sapere quale formato si aspetta l'API di Adobe. Tuttavia, dovrebbe esserci una spiegazione all'inizio della maggior parte della documentazione che spieghi le convenzioni utilizzate all'interno di.

Quindi, questa funzione potrebbe probabilmente essere utilizzata in molti modi:

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

Di nuovo, di solito ci sono alcuni standard in tutte le documentazioni relative all'API / programmazione. Tuttavia in ogni documento potrebbero esserci sottili differenze. In qualità di utente esperto o sviluppatore, DOVRESTE essere in grado di leggere e comprendere i documenti / framework / librerie che stai tentando di utilizzare.

I documenti API per i linguaggi tipizzati dinamicamente possono essere poco significativi se non scritti con attenzione, quindi non sentirti troppo male, anche lo sviluppatore più esperto può avere difficoltà a cercare di capirli.

Riguardo alle parentesi e simili, di solito c'è una sezione delle convenzioni del codice che dovrebbe spiegare l'uso esatto al di fuori degli esempi letterali; sebbene EBNF , Regex e Railroad Diagrams siano quasi onnipresenti, quindi dovresti avere familiarità con loro per capire la maggior parte delle notazioni.

Le parentesi indicano che la proprietà è facoltativa. Tieni presente però che se vuoi impostare alcune proprietà al rango nTh, devi dichiarare le proprietà per quella iniziale o dichiararle come non definite:

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

Ho avuto la stessa domanda qualche tempo fa e qualcuno mi ha indicato la forma Extended Backus-Naur .

Ha senso perché la programmazione può essere utilizzata per creare risultati potenzialmente illimitati. La documentazione non può visualizzare un esempio per ogni possibile caso. Un buon esempio di uso comune mi è d'aiuto, ma una volta che puoi leggere la sintassi sottostante puoi creare il tuo codice.