Saya memiliki fungsi yang menerima satu parameter string. Parameter ini hanya dapat memiliki satu dari beberapa kemungkinan nilai yang ditentukan. Apa cara terbaik untuk mendokumentasikan hal yang sama? Haruskah shapeType didefinisikan sebagai enum atau TypeDef atau yang lainnya?
Shape.prototype.create = function (shapeType) {
// shapeType can be "rect", "circle" or "ellipse"...
this.type = shapeType;
};
Shape.prototype.getType = function (shapeType) {
// shapeType can be "rect", "circle" or "ellipse"...
return this.type;
};
Bagian kedua dari masalah adalah bahwa nilai yang mungkin dari shapeType
tidak diketahui dalam file yang didefinisikan shapeType
sebagai apapun yang Anda sarankan. Ada beberapa file yang disumbangkan oleh beberapa pengembang yang mungkin menambah nilai yang mungkin dari shapeType
.
PS: Saya menggunakan jsdoc3
google-closure-compiler
google-closure
jsdoc
code-documentation
Shamasis Bhattacharya
sumber
sumber
enum
untuk definisi dan serikat untuk parameter fungsi:ShapeType|string
. Namun enum tidak mendukung penambahan subtipe setelah deklarasi di Closure-compiler.Jawaban:
Bagaimana dengan mendeklarasikan dummy enum:
Anda harus setidaknya mendeklarasikan enum ke JSDOC, untuk ini. Tetapi kodenya bersih dan Anda mendapatkan pelengkapan otomatis di WebStorm.
Masalah banyak file meskipun tidak dapat diselesaikan dengan cara ini.
sumber
Pada akhir 2014 di jsdoc3 Anda memiliki kemungkinan untuk menulis:
Tentu saja ini tidak akan dapat digunakan kembali sebagai enum khusus tetapi dalam banyak kasus enum dummy berlebihan jika hanya digunakan oleh satu fungsi.
Lihat juga: https://github.com/jsdoc3/jsdoc/issues/629#issue-31314808
sumber
Bagaimana dengan:
sumber
Saya tidak berpikir ada cara formal untuk menulis nilai yang diperbolehkan di JSDoc .
Anda pasti bisa menulis sesuatu
@param {String('up'|'down'|'left'|'right')}
seperti pengguna b12toaster disebutkan.Tapi, dengan mengambil referensi dari APIDocjs , inilah yang saya gunakan untuk menulis nilai yang dibatasi, alias allowValues .
Oh ya, saya menggunakan ES6.
sumber
Beginilah cara Closure Compiler mendukungnya: Anda dapat menggunakan "@enum" untuk menentukan tipe terbatas. Anda tidak benar-benar harus mendefinisikan nilai dalam definisi enum. Misalnya, saya mungkin mendefinisikan jenis "integer" seperti:
Int umumnya dapat ditetapkan ke "angka" (ini adalah angka) tetapi "angka" tidak dapat ditetapkan ke "Int" tanpa paksaan (cor).
sumber
Int
. Itu bagian yang saya tidak yakin mungkin.