Cara mendokumentasikan tipe string di jsdoc dengan kemungkinan nilai terbatas

96

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 shapeTypetidak diketahui dalam file yang didefinisikan shapeTypesebagai apapun yang Anda sarankan. Ada beberapa file yang disumbangkan oleh beberapa pengembang yang mungkin menambah nilai yang mungkin dari shapeType.

PS: Saya menggunakan jsdoc3

Shamasis Bhattacharya
sumber
Masalah banyak file membuat ini sulit. Saya biasanya melihat enumuntuk definisi dan serikat untuk parameter fungsi: ShapeType|string. Namun enum tidak mendukung penambahan subtipe setelah deklarasi di Closure-compiler.
Chad Killingsworth
@ChadKillingsworth Saya mengerti apa yang Anda maksud. Saya terjebak pada titik di mana saya ingin mendefinisikan satu set properti (katakanlah sebuah objek yang berfungsi sebagai parameter konstruksi kelas). Baik dan bagus jika semua properti konstruksi ditentukan di satu lokasi. Sayangnya, kode saya memiliki sejumlah modul yang berkontribusi pada properti konstruksi tersebut. Melakukan sesuatu seperti mixin atau subclassing properti akan berlebihan! Karena itu, jika saya bisa memasukkan definisi daftar properti, itu akan bagus.
Shamasis Bhattacharya
Masalah serupa lainnya yang saya hadapi, tetapi dengan daftar properti terdistribusi adalah stackoverflow.com/questions/19113571/…
Shamasis Bhattacharya
Semua solusi di bawah ini memaksa kita untuk membuat Enum. Ada permintaan fitur aktif di GitHub untuk mempermudah proses ini: github.com/jsdoc3/jsdoc/issues/629 . Jadi siapa pun yang menyukainya mungkin harus menabraknya.
B12Toaster

Jawaban:

26

Bagaimana dengan mendeklarasikan dummy enum:

/**
 * Enum string values.
 * @enum {string}
 */
Enumeration = {
    ONE: "The number one",
    TWO: "A second number"
};

/**
 * Sample.
 * @param {Enumeration} a one of the enumeration values.
 */
Bar.prototype.sample = function(a) {};


b = new Bar();

bar.sample(Enumeration.ONE)

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.

Sebastian
sumber
Iya. Pendekatan pencacahan adalah satu-satunya cara yang dapat digunakan yang saya lihat. Bagaimanapun, saya menerima ini sebagai satu-satunya jawaban yang dapat digunakan - karena masalah multi-file adalah cerita lain sama sekali!
Shamasis Bhattacharya
Masalah dengan pendekatan ini adalah tidak memungkinkan untuk mendokumentasikan nilai-nilai individu. Saya memiliki masalah dengan JSDoc. github.com/jsdoc3/jsdoc/issues/1065
Gajus
113

Pada akhir 2014 di jsdoc3 Anda memiliki kemungkinan untuk menulis:

/**
 * @param {('rect'|'circle'|'ellipse')} shapeType - The allowed type of the shape
 */
Shape.prototype.getType = function (shapeType) {
  return this.type;
};

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

B12Pemanggang
sumber
4
Ini adalah solusi yang lebih baik jika Anda tahu bahwa tipe param tidak akan pernah berubah.
Luca Steeb
1
Solusi terbaik untuk ini menurut saya! Terima kasih.
AJC24
27

Bagaimana dengan:

/**
 * @typedef {"keyvalue" | "bar" | "timeseries" | "pie" | "table"} MetricFormat
 */

/**
 * @param format {MetricFormat}
 */
export function fetchMetric(format) {
    return fetch(`/matric}`, format);
}

masukkan deskripsi gambar di sini

puemos
sumber
9

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.

masukkan deskripsi gambar di sini

Tapi, dengan mengambil referensi dari APIDocjs , inilah yang saya gunakan untuk menulis nilai yang dibatasi, alias allowValues .

/**
 * Set the arrow position of the tooltip
 * @param {String='up','down','left','right'} position pointer position
 */
setPosition(position='left'){
  // YOUR OWN CODE
}

Oh ya, saya menggunakan ES6.

Alan Dong
sumber
0

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:

/** @enum {number} */
var Int = {};

/** @return {Int} */
function toInt(val) {
  return /** @type {Int} */ (val|0);
}

Int umumnya dapat ditetapkan ke "angka" (ini adalah angka) tetapi "angka" tidak dapat ditetapkan ke "Int" tanpa paksaan (cor).

John
sumber
Tapi itu tidak membatasi kemungkinan nilai Int. Itu bagian yang saya tidak yakin mungkin.
Chad Killingsworth
Ia melakukan sebanyak anotasi jenis lain atau enum di JS. Pembatasan berasal dari cara Anda menulis kode: setiap "pemeran" adalah bendera merah. Jika Anda membatasi pemain untuk menilai pabrik maka Anda mendapatkan apa yang Anda inginkan: Anda tidak dapat menetapkan 'nomor' ke 'Int' tanpa peringatan.
Yohanes
Itu masih tidak membatasi nilai {Int}. :-(
Shamasis Bhattacharya
Tentu saja, Anda membatasi nilai Int dengan membatasi cara pembuatannya dan pembatasan dilakukan saat nilai dibuat. Nomor mentah tidak dapat diberikan yang hanya Anda butuhkan.
Yohanes