Cách ghi lại kiểu chuỗi trong jsdoc với các giá trị giới hạn có thể có

Tôi đang có một hàm chấp nhận một tham số chuỗi. Tham số này chỉ có thể có một trong một vài giá trị có thể được xác định. Cách tốt nhất để ghi lại tài liệu giống nhau là gì? ShapeType có nên được định nghĩa là enum hoặc TypeDef hay thứ gì khác không?

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

Phần thứ hai của vấn đề là các giá trị có thể shapeTypekhông được biết đến trong tệp xác định shapeTypelà bất kỳ giá trị nào bạn đề xuất. Có nhiều tệp được đóng góp bởi một số nhà phát triển, những người có thể thêm vào các giá trị có thể có của shapeType.

PS: Đang sử dụng jsdoc3

Làm thế nào về việc khai báo một enum giả:

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

Tuy nhiên, ít nhất bạn cần khai báo enum cho JSDOC. Nhưng mã sạch và bạn nhận được tự động hoàn thành trong WebStorm.

Tuy nhiên, vấn đề nhiều tệp không thể được giải quyết theo cách này.

Tính đến cuối năm 2014 trong jsdoc3, bạn có thể viết:

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

Tất nhiên điều này sẽ không thể tái sử dụng như enum chuyên dụng nhưng trong nhiều trường hợp, enum giả là quá mức cần thiết nếu nó chỉ được sử dụng bởi một chức năng.

Xem thêm: https://github.com/jsdoc3/jsdoc/issues/629#issue-31314808

Thế còn:

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

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

Tôi không nghĩ rằng có một cách chính thức để viết các giá trị được phép trong JSDoc .

Bạn chắc chắn có thể viết một cái gì đó giống @param {String('up'|'down'|'left'|'right')}như người dùng b12toaster đã đề cập.

Nhưng, bằng cách lấy tham chiếu từ APIDocjs , đây là những gì tôi sử dụng để viết các giá trị bị ràng buộc, hay còn gọi là Giá trị được phép .

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

Ồ đúng rồi, tôi đang sử dụng ES6.

Đây là cách mà Trình biên dịch đóng cửa hỗ trợ nó: bạn có thể sử dụng "@enum" để xác định một kiểu hạn chế. Bạn không thực sự phải xác định các giá trị trong định nghĩa enum. Ví dụ: tôi có thể xác định kiểu "số nguyên" như:

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

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

Int thường có thể gán cho "number" (nó là một số) nhưng "number" không thể gán cho "Int" nếu không có sự ép buộc nào đó (cast).