// My function does X and Y.
// @params {object} parameters An object containing the parameters
// @params {function} callback The callback function
function(parameters, callback) {
}
Tetapi bagaimana saya menggambarkan bagaimana objek parameter harus disusun? Contohnya harus seperti:
{
setting1 : 123, // (required, integer)
setting2 : 'asdf' // (optional, string)
}
javascript
jsdoc
Andy Hin
sumber
sumber
action
nama, saya menulis `foo = ({arg1, arg2, arg2}) => {...}`. Sunting: pertanyaan di sini stackoverflow.com/questions/36916790/…Sekarang ada 4 cara berbeda untuk mendokumentasikan objek sebagai parameter / tipe. Masing-masing memiliki kegunaan sendiri. Hanya 3 dari mereka yang dapat digunakan untuk mendokumentasikan nilai pengembalian.
Untuk objek dengan set properti yang dikenal (Varian A)
Sintaks ini sangat ideal untuk objek yang hanya digunakan sebagai parameter untuk fungsi ini dan tidak memerlukan deskripsi lebih lanjut dari setiap properti. Dapat digunakan untuk
@returns
juga .Untuk objek dengan set properti yang dikenal (Varian B)
Sangat berguna adalah parameter dengan sintaksis properti :
Sintaks ini sangat ideal untuk objek yang hanya digunakan sebagai parameter untuk fungsi ini dan yang memerlukan deskripsi lebih lanjut dari setiap properti. Ini tidak dapat digunakan untuk
@returns
.Untuk objek yang akan digunakan di lebih dari satu titik dalam sumber
Dalam hal ini @typedef sangat berguna. Anda dapat menentukan jenis pada satu titik di sumber Anda dan menggunakannya sebagai jenis untuk
@param
atau@returns
atau tag JSDoc lainnya yang dapat menggunakan suatu jenis.Anda kemudian dapat menggunakan ini dalam
@param
tag:Atau dalam
@returns
:Untuk objek yang nilainya semua jenis yang sama
Jenis pertama (string) mendokumentasikan jenis kunci yang dalam JavaScript selalu berupa string atau setidaknya akan selalu dipaksa ke string. Tipe kedua (angka) adalah tipe nilai; ini bisa berupa tipe apa saja. Sintaks ini dapat digunakan untuk
@returns
juga.Sumber daya
Informasi yang berguna tentang tipe-tipe dokumentasi dapat ditemukan di sini:
https://jsdoc.app/tags-type.html
PS:
untuk mendokumentasikan nilai opsional yang dapat Anda gunakan
[]
:atau:
sumber
{{dir: A|B|C }}
?{[myVariable]: string}
Saya melihat bahwa sudah ada jawaban tentang tag @return, tetapi saya ingin memberikan rincian lebih lanjut tentang hal itu.
Pertama-tama, dokumentasi JSDoc 3 resmi tidak memberikan contoh tentang @return untuk objek kustom. Silakan lihat https://jsdoc.app/tags-returns.html . Sekarang, mari kita lihat apa yang bisa kita lakukan sampai beberapa standar muncul.
Fungsi mengembalikan objek tempat kunci dihasilkan secara dinamis. Contoh:
{1: 'Pete', 2: 'Mary', 3: 'John'}
. Biasanya, kami mengulangi objek ini dengan bantuanfor(var key in obj){...}
.Kemungkinan JSDoc menurut https://google.github.io/styleguide/javascriptguide.xml#JsTypes
Fungsi mengembalikan objek di mana kunci dikenal konstanta. Contoh:
{id: 1, title: 'Hello world', type: 'LEARN', children: {...}}
. Kita dapat dengan mudah mengakses properti dari objek ini:object.id
.Kemungkinan JSDoc menurut https://groups.google.com/forum/#!topic/jsdoc-users/TMvUedK9tC4
Berpura-pura.
Monty Penuh.
Tentukan tipe.
Menurut https://google.github.io/styleguide/javascriptguide.xml#JsTypes
Jenis rekaman.
sumber
Untuk
@return
penggunaan tag{{field1: Number, field2: String}}
, lihat: http://wiki.servoy.com/display/public/DOCS/Annotating+JavaScript+using+JSDocsumber
Sumber: JSDoc
sumber
Ada
@config
tag baru untuk kasus ini. Mereka terhubung ke sebelumnya@param
.sumber
@config
tag? Saya tidak menemukan apa pun di usejsdoc.org , dan halaman ini menunjukkan@config
telah usang.@config
sudah usang pada saat ini. YUIDoc merekomendasikan penggunaannya@attribute
sebagai gantinya.