제한된 가능한 값으로 jsdoc에서 문자열 유형을 문서화하는 방법


98

하나의 문자열 매개 변수를 받아들이는 함수가 있습니다. 이 매개 변수는 정의 된 몇 가지 가능한 값 중 하나만 가질 수 있습니다. 이를 문서화하는 가장 좋은 방법은 무엇입니까? 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함수 매개 변수에 대한 정의와 공용체를 ShapeType|string봅니다. 그러나 열거 형은 Closure-compiler에서 선언 후 하위 유형 추가를 지원하지 않습니다.
Chad Killingsworth 2013 년

@ChadKillingsworth 무슨 말인지 알 겠어요. 속성 집합을 정의하려는 지점에 갇혀 있습니다 (클래스의 구성 매개 변수로 사용되는 개체를 말합니다). 건설의 모든 속성이 한 위치에서 정의되었으므로 훌륭하고 좋습니다. 불행히도 내 코드에는 해당 구성 속성에 기여하는 여러 모듈이 있습니다. 믹스 인이나 속성을 서브 클래 싱하는 것과 같은 일을하는 것은 배가 될 것입니다! 따라서 속성 목록 정의에 간단히 삽입 할 수 있다면 좋을 것입니다.
Shamasis Bhattacharya

내가 직면하고있는 또 다른 유사한 문제이지만 분산 된 부동산 목록과 함께 stackoverflow.com/questions/19113571/…
Shamasis Bhattacharya

아래의 모든 솔루션은 Enum을 생성하도록합니다. 이 프로세스를 훨씬 쉽게하기 위해 GitHub에 활성 기능 요청이 있습니다 : github.com/jsdoc3/jsdoc/issues/629 . 그래서 그것을 좋아하는 사람은 아마 그것을 부딪쳐 야 할 것입니다.
B12Toaster

답변:


26

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

/**
 * 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에서 자동 완성됩니다.

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


예. 열거 접근 방식은 내가 볼 수있는 유일한 사용 가능한 방법입니다. 어쨌든, 나는 이것을 유일하게 사용할 수있는 대답으로 받아들입니다. 다중 파일 문제는 완전히 다른 이야기이기 때문입니다!
Shamasis Bhattacharya

이 접근법의 문제점은 개별 값을 문서화 할 수 없다는 것입니다. JSDoc에 문제가 있습니다. github.com/jsdoc3/jsdoc/issues/1065
Gajus 2015-09-17

116

현재로 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


4
매개 변수 유형이 절대 변경되지 않는다는 것을 알고 있다면 더 나은 솔루션입니다.
Luca Steeb

1
내 관점에서 이것에 대한 최고의 솔루션! 감사합니다.
AJC24

27

는 어때:

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

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

여기에 이미지 설명 입력


9

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를 사용하고 있습니다.


0

이것이 Closure Compiler가이를 지원하는 방법입니다. "@enum"을 사용하여 제한된 유형을 정의 할 수 있습니다. 실제로 열거 형 정의에서 값을 정의 할 필요는 없습니다. 예를 들어 다음과 같이 "정수"유형을 정의 할 수 있습니다.

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

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

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


그러나 그것은 가능한 값을 제한하지 않습니다 Int. 그것이 가능한지 확실하지 않은 부분입니다.
Chad Killingsworth

JS의 다른 유형 주석 또는 열거 형만큼 많이 수행합니다. 제한은 코드 작성 방식에서 비롯됩니다. 모든 "캐스트"는 위험 신호입니다. 캐스트를 값 팩토리로 제한하면 원하는 것을 얻을 수 있습니다. 경고없이 'Int'에 'number'를 할당 할 수 없습니다.
John

여전히 {Int}의 값을 제한하지 않습니다. :-(
Shamasis Bhattacharya 2010 년

물론 Int의 생성 방법을 제한하여 Int 값을 제한하고 값이 생성 될 때 제한이 수행됩니다. 필요한 전부인 원시 번호를 할당 할 수 없습니다.
당사 사이트를 사용함과 동시에 당사의 쿠키 정책개인정보 보호정책을 읽고 이해하였음을 인정하는 것으로 간주합니다.
Licensed under cc by-sa 3.0 with attribution required.