Bagaimana menafsirkan parameter fungsi dokumentasi API?


103

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

4
Apakah ada pengantar dokumen referensi API yang menjelaskan konvensi sintaksisnya?
Greg Hewgill

35
Untuk orang yang memilih untuk menutup: Saya yakin pertanyaan ini bermanfaat, dan akan "memilih untuk tidak menutup" jika saya bisa. Ini bukan pertanyaan yang pernah saya lihat (atau dengar) tanyakan sebelumnya, ini membahas masalah terkait pemrograman yang sah, dan saya pribadi akan menemukan jawabannya berguna ketika saya mengajari orang hal-hal yang terkait dengan pemrograman.
David Wolever

4
Derek: Saya rasa Anda melewatkan salah satu kalimat tebal di postingan aslinya. Jika Anda google "cara membaca dokumentasi api", info di 10 hasil pertama mengatakan hal-hal seperti "abstrak", "tidak lengkap", "membingungkan", dll., Sehingga memperkuat inti pertanyaan saya.
dbonneville

2
Greg: Tidak ada perkenalan dengan produk Photoshop / Adobe. Semuanya mengikuti format yang sama dalam 2 PDF per produk. API lain yang saya pikirkan melakukan hal yang sama. Ada pengetahuan implisit yang dalam banyak kasus tidak saya miliki dan pasti ingin saya miliki.
dbonneville

1
Sumber daya yang berguna adalah penampil objek yang dibangun ke dalam Extendscript IDE (tekan F1). Mengklik objek akan menunjukkan properti dan metode apa yang dimilikinya. Juga jika ia menggunakan objek lain sebagai parameter yang (biasanya) ditautkan ke mereka sehingga Anda dapat melihat properti apa yang mereka miliki juga. Itu tidak sempurna tapi membantu.
pdizz

Jawaban:


92

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.


5
Link format sinopsis halaman manual UNIX sudah mati - ada yang punya link pengganti? Pembaruan @PenguinCoder: Berdasarkan [ unix.stackexchange.com/questions/17833/… (Unix Stack Exchange), Ini secara longgar didasarkan pada [ en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_Form (EBNF)
steviejay

Ada salinan arsip dari format yang man page synposis
CodeManX

5

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.


3

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

2
fillPath (mode)mungkin baik-baik saja. Jika argumen opsional muncul sebelum argumen non-opsional itu sering berarti bahwa fungsinya cukup pintar untuk mendeteksi apakah argumen opsional diberikan atau tidak (misalnya dengan melihat tipenya)
ThiefMaster

1
MMmm, itu mungkin tapi saya lebih suka mengandalkan sesuatu yang kuat daripada sesuatu yang mungkin dilakukan skrip untuk saya: D
Loic Aigon

1

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.

Dengan menggunakan situs kami, Anda mengakui telah membaca dan memahami Kebijakan Cookie dan Kebijakan Privasi kami.
Licensed under cc by-sa 3.0 with attribution required.