Bagaimana menafsirkan parameter fungsi dokumentasi API?

Apakah ada standar untuk menafsirkan sintaks antarmuka fungsi dalam dokumentasi API dan jika ya, bagaimana itu didefinisikan?

Berikut adalah contoh tentang cara mengubah warna item panduan skrip JavaScript untuk Photoshop untuk fungsi "fillColor":

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

Apa arti tanda kurung dan mengapa ada koma di tanda kurung? Bagaimana ini berhubungan dengan contoh panggilan berikut?

myPath.fillPath(myNewColor)

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

Jadi mengapa dokumentasi API ditulis sedemikian rupa sehingga membingungkan newbs / peretas / DIYer abadi seperti saya?

Sebenarnya tidak dimaksudkan untuk ditulis seperti itu. Saya setuju bahwa tampaknya tidak ada kemudahan penggunaan di seluruh dokumentasi API. Namun, ada banyak persilangan dari mankonvensi sintaks gaya lama , ke konvensi API / namespace modern.

Biasanya, tipe orang yang bekerja dengan API, akan memiliki latar belakang dalam pengembangan atau setidaknya 'pengguna yang kuat'. Jenis pengguna ini terbiasa dengan konvensi sintaksis dan lebih masuk akal untuk diikuti dokumen API daripada mencoba membuat yang baru.

Apakah ada dokumen misterius di suatu tempat yang memberi tahu orang-orang cara membaca dokumentasi API?

Benar-benar tidak ada standar, atau RFC, supersekretsyntaxdoc yang diletakkan di mana saja, namun ada file berusia ~ 30 tahun untuk format synposis halaman manual UNIX yang digunakan secara luas.

Beberapa contohnya (dan menjawab pertanyaan Anda) adalah:

Kata-kata yang digarisbawahi dianggap literal, dan diketik seperti yang muncul.

Tanda kurung siku ([]) di sekitar argumen menunjukkan bahwa argumen tersebut opsional.

Elipsis ... digunakan untuk menunjukkan bahwa argumen-prototipe sebelumnya dapat diulang.

Argumen yang dimulai dengan tanda minus - sering diartikan sebagai semacam argumen bendera bahkan jika muncul dalam posisi di mana nama file dapat muncul.

Hampir semua dokumentasi terkait pemrograman menggunakan jenis konvensi sintaksis ini, dari Python , halaman manual , javascript libs ( Highcharts ), dll.

Memecah contoh Anda dari Adobe API

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

Kami melihat bahwa fillPath()(fungsi) mengambil argumen opsional fillColor, mode, opacity, preserveTransparency, feathe, wholePathatau antiAlias. Memanggil fillPath(), Anda bisa meneruskan di mana saja dari tidak ada, ke semua, parameter itu ke sana. Tanda koma dalam opsional []berarti bahwa jika parameter ini digunakan selain yang lain, Anda memerlukan koma untuk memisahkannya. (Akal sehat kadang-kadang, pasti, tetapi kadang-kadang beberapa bahasa seperti VB, secara eksplisit membutuhkan koma tersebut untuk menggambarkan dengan tepat parameter mana yang hilang!). Karena Anda tidak menautkan ke dokumentasi (dan saya tidak dapat menemukannya di halaman scripting Adobe ) sebenarnya tidak ada cara untuk mengetahui format mana yang diharapkan Adobe API. Namun, harus ada penjelasan di bagian atas sebagian besar dokumentasi yang menjelaskan konvensi yang digunakan di dalamnya.

Jadi, fungsi ini mungkin bisa digunakan dengan berbagai cara:

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

Sekali lagi, biasanya ada beberapa standar di semua dokumentasi yang berkaitan dengan API / pemrograman. Namun di setiap dokumen, mungkin ada perbedaan kecil. Sebagai power user, atau developer, Anda DIHARAPKAN untuk dapat membaca dan memahami dokumen / framework / library yang Anda coba gunakan.

Dokumen API untuk bahasa yang diketik secara dinamis dapat menjadi tidak berarti jika tidak ditulis dengan hati-hati, jadi jangan merasa terlalu buruk tentangnya, bahkan pengembang yang paling berpengalaman pun dapat mengalami kesulitan untuk mencoba memahaminya.

Tentang tanda kurung dan semacamnya, biasanya ada bagian konvensi kode yang harus menjelaskan penggunaan yang tepat di luar contoh literal; meskipun EBNF , Regex dan Diagram Rel Kereta hampir ada di mana-mana, jadi Anda harus terbiasa dengannya untuk memahami sebagian besar notasi.

Tanda kurung berarti bahwa properti tersebut opsional. Ketahuilah bahwa jika Anda ingin menyetel beberapa properti di peringkat nTh, Anda harus mendeklarasikan properti untuk yang terdepan atau mendeklarasikannya sebagai tidak terdefinisi:

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

Saya memiliki pertanyaan yang sama beberapa waktu lalu dan seseorang mengarahkan saya ke Formulir Extended Backus-Naur .

Masuk akal karena pemrograman dapat digunakan untuk menciptakan hasil yang berpotensi tidak terbatas. Dokumentasi tidak dapat menampilkan contoh untuk setiap kasus yang memungkinkan. Sebuah contoh yang baik dari penggunaan umum Saya membantu tetapi setelah Anda dapat membaca sintaks yang mendasari Anda dapat membuat kode Anda sendiri.