Cara mendokumentasikan tipe string di jsdoc dengan kemungkinan nilai terbatas

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

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.

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

Bagaimana dengan:

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

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

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 .

/**
 * 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.

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