JSDoc에서 개방형 인수 함수를 문서화하는 올바른 방법

다음과 같은 것이 있다고 가정 해 보겠습니다.

var someFunc = function() {
    // do something here with arguments
}

이 함수가 JSDoc에서 여러 인수를 취할 수 있다는 것을 어떻게 올바르게 문서화 할 수 있습니까? 이것이 내 최선의 추측이지만 정확한지 모르겠습니다.

/**
 * @param {Mixed} [...] Unlimited amount of optional parameters
 */
var someFunc = function() {
    // do something here with arguments
}

관련 항목 : php-가변 개수의 매개 변수를 문서화하는 방법

JSDoc 사양 과 구글의 폐쇄 컴파일러는 이런 식으로 할 :

@param {...number} var_args

여기서 "number"는 예상되는 인수 유형입니다.

그러면 이것의 전체 사용법은 다음과 같습니다.

/**
* @param {...*} var_args
*/
function lookMaImVariadic(var_args) {
    // Utilize the `arguments` object here, not `var_args`.
}

추가 인수에 액세스하기 위해 활용 arguments(또는의 일부 오프셋 arguments)에 대한 주석을 참고하십시오 . var_args인수가 실제로 존재한다는 것을 IDE에 알리는 데 사용되었습니다.

ES6의 나머지 매개 변수 는 제공된 값을 포함하기 위해 실제 매개 변수를 한 단계 더 사용할 수 있으므로 더 이상 사용할 arguments필요가 없습니다 .

/**
* @param {...*} var_args
*/
function lookMaImES6Variadic(...var_args) {
    // Utilize the `var_args` array here, not `arguments`.
}

이를 수행하는 방법은 이제 JSDoc 문서에 설명 되어 있으며 Closure 문서와 같은 줄임표를 사용합니다.

@param {...<type>} <argName> <Argument description>

줄임표 뒤에 오는 유형을 제공해야하지만 a *를 사용하여 허용 되는 것을 설명하거나를 사용하여 |여러 허용되는 유형을 구분할 수 있습니다. 생성 된 문서에서 JSDoc은이 인수를 반복 가능한 것으로 설명합니다. 동일한 방식으로 선택적 인수를 선택 사항으로 설명 합니다.

내 테스트에서 실제 자바 스크립트 함수 정의에 인수를 가질 필요가 없었으므로 실제 코드는 빈 괄호, 즉 function whatever() { ... }.

단일 유형 :

@param {...number} terms Terms to multiply together

모든 유형 (아래 예에서 대괄호는 items선택 및 반복 가능으로 태그가 지정됨을 의미 함 ) :

@param {...*} [items] - zero or more items to log.

여러 유형은 유형 목록을 괄호로 묶어야하며 여는 괄호 앞에 줄임표가 있어야합니다.

@param {...(Person|string)} attendees - Meeting attendees, listed as either 
                                        String names or {@link Person} objects

로부터 JSDoc 사용자 그룹 :

공식적인 방법은 없지만 가능한 한 가지 해결책은 다음과 같습니다.

/**
 * @param [...] Zero or more child nodes. If zero then ... otherwise ....
 */

대괄호는 선택적 매개 변수를 나타내며 ...는 "임의의 숫자"를 나타냅니다.

또 다른 가능성은 이것입니다 ...

/**
 * @param [arguments] The child nodes.
 */

어느 쪽이든 당신이 의미하는 바를 전달해야합니다.

그러나 (2007) 약간 날짜가 있지만 더 최신 정보는 알지 못합니다.

매개 변수 유형을 'mixed'로 문서화해야하는 경우 {*}에서와 같이를 사용하십시오 @param {*} [arguments].

나는 꽤 오랫동안 이것을 가지고 있었다. Google Closure Compiler로 수행하는 방법은 다음과 같습니다.

/**
* @param {...*} var_args
*/
function my_function(var_args) {
    // code that accesses the magic 'arguments' variable...
}

핵심은 함수가 실제로 해당 매개 변수를 사용하지 않더라도 함수에 var_args매개 변수 (또는 @param명령문 에서 호출하는 모든 것 )를 제공하는 것입니다.