제한된 가능한 값으로 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

더미 열거 형을 선언하는 것은 어떻습니까?

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

그래도 적어도 열거 형을 JSDOC에 선언해야합니다. 그러나 코드는 깨끗하고 WebStorm에서 자동 완성됩니다.

여러 파일 문제는이 방법으로 해결할 수 없습니다.

현재로 2014 년 말 당신이 쓸 수있는 가능성이 jsdoc3에서 :

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

물론 이것은 전용 열거 형만큼 재사용 할 수는 없지만 많은 경우 더미 열거 형은 하나의 함수에서만 사용되는 경우 과잉입니다.

참조 : 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 {number} */
var Int = {};

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

Int는 일반적으로 "number"(숫자)에 할당 할 수 있지만 "number"는 일부 강제 (캐스트)없이 "Int"에 할당 할 수 없습니다.