วิธีจัดทำเอกสารประเภทสตริงใน jsdoc ด้วยค่าที่เป็นไปได้ที่ จำกัด

ฉันมีฟังก์ชันที่ยอมรับพารามิเตอร์สตริงหนึ่งตัว พารามิเตอร์นี้สามารถมีค่าที่เป็นไปได้ที่กำหนดไว้เพียงไม่กี่ค่าเท่านั้น วิธีที่ดีที่สุดในการจัดทำเอกสารแบบเดียวกันคืออะไร? ควรกำหนด shapeType เป็น enum หรือ TypeDef หรืออย่างอื่น?

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

ส่วนที่สองของปัญหาคือค่าที่เป็นไปได้ของshapeTypeไม่เป็นที่รู้จักในไฟล์ที่กำหนดshapeTypeเป็นสิ่งที่คุณแนะนำ มีไฟล์หลายไฟล์ที่มาจากนักพัฒนาหลายคนซึ่งอาจเพิ่มค่าที่เป็นไปได้ของshapeTypeไฟล์.

PS: กำลังใช้ jsdoc3

วิธีการประกาศ 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)

อย่างน้อยคุณต้องประกาศ enum ต่อ JSDOC สำหรับสิ่งนี้แม้ว่า แต่รหัสนั้นสะอาดและคุณได้รับการเติมข้อความอัตโนมัติใน WebStorm

ปัญหาหลายไฟล์ไม่สามารถแก้ไขได้ด้วยวิธีนี้

เมื่อปลายปี 2014ใน jsdoc3 คุณมีความเป็นไปได้ที่จะเขียน:

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

แน่นอนว่าสิ่งนี้จะไม่สามารถนำมาใช้ซ้ำได้เหมือนกับ enum เฉพาะ แต่ในหลาย ๆ กรณี dummy enum จะเกินความจำเป็นหากใช้เพียงฟังก์ชันเดียว

ดูเพิ่มเติม: https://github.com/jsdoc3/jsdoc/issues/629#issue-31314808

สิ่งที่เกี่ยวกับ:

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

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

ฉันไม่คิดว่ามีวิธีการเขียนอย่างเป็นทางการของค่าอนุญาตให้ใช้ในJSDoc

แน่นอนคุณสามารถเขียนบางอย่าง@param {String('up'|'down'|'left'|'right')}เช่นผู้ใช้b12toasterกล่าวถึง

แต่โดยการอ้างอิงจากAPIDocjsนี่คือสิ่งที่ฉันจะใช้สำหรับการเขียนค่า จำกัด อาคาallowedValues

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

ใช่ฉันใช้ ES6

นี่คือวิธีที่ Closure Compiler รองรับ: คุณสามารถใช้ "@enum" เพื่อกำหนดประเภทที่ จำกัด ได้ คุณไม่จำเป็นต้องกำหนดค่าในนิยาม enum ตัวอย่างเช่นฉันอาจกำหนดประเภท "จำนวนเต็ม" เช่น:

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

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

โดยทั่วไป Int จะกำหนดให้กับ "number" (คือตัวเลข) แต่ "number" ไม่สามารถกำหนดให้กับ "Int" ได้หากไม่มีการบังคับ (การร่าย)