문서에 메타데이터 추가
좋은 문서를 제공하는 것은 모든 개발자에게 필수적인 작업입니다. 동료들이 당신의 추론과 생각하는 과정을 빠르게 이해하는 데 도움이 될 뿐만 아니라 몇 달 후에 다시 코드를 사용할 경우에 대비하여 코드에 더 빨리 들어갈 수 있도록 도와줍니다.
따라서 JSDoc-comments와 함께 사용할 특수 태그의 (불완전한) 목록을 만들려고 생각했습니다. 이것들은 제가 개인적으로 가장 자주 사용하고 실제 이점을 제공하는 것으로 입증된 것입니다.
기본 스타터
다음 코드 예제는 모든 문서에 사용해야 하는 간단하고 기본적인 예제를 보여줍니다. 목적, 매개변수 및 반환 유형에 주석을 답니다.
/**
* Get a sum all terms provided.
*
* @param {...number} terms Array of terms to sum up.
* @returns {number} Sum of terms.
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
문서의 예제 코드
특정 사용 사례를 더 명확하게 하기 위해 "@example"-태그와 함께 실제 인라인 코드 예제를 제공할 수 있습니다. 이 태그는 실제 시나리오에서 가능한 극단적인 경우를 빠르게 표시하는 데 사용할 수도 있습니다.
/**
* Get a sum all terms provided.
*
* @example
* ```ts
* import { sum } from "./source";
* const result = sum(40, 2);
* ```
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
어느 모듈의 멤버
"@memberOf" 태그를 사용하여 문서화된 코드를 호스팅하는 모듈 또는 상위 변수를 정의합니다.
/**
* @memberOf module:source
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
링크 주석
"@see" 태그를 "@link" 태그와 함께 사용하여 기본 문서의 인라인에 일부 URL을 붙여넣는 대신 올바른 형식의 URL 문서를 제공할 수 있습니다.
/**
* @see (@link module:source.sum}
* @see (@link https://www.some-source.com}
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
제네릭 유형 문서
코드에서 제네릭 유형을 사용하는 경우 "@template" 태그를 사용하여 제네릭 유형 이름을 정의할 수 있습니다. 이 이름은 공통 "@param" 태그에서 유형 참조로 사용됩니다.
/**
* @template T
* @param {...T} Array of numbers to sum up.
* @returns {number} Sum of terms.
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
코드의 작성자 정의
어떤 경우에는 작성자에게도 주석을 달아야 합니다. 이것은 "@author" 태그로 간단히 수행할 수 있습니다. 이름뿐만 아니라 연락처 참조로 이메일도 제공할 수 있습니다.
/**
* @author Tom Schönmann <[email protected]>
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
사용되지 않는 코드
"@deprecated" 태그에 대해 설명할 내용이 많지 않습니다. 예상한 것과 정확히 일치하기 때문입니다. 이 태그는 API에서 일반적으로 사용되며 새 코드를 참조할 수도 있습니다.
/**
* @deprecated Use 'add(...)' instead.
* @see {@link module:source/add}
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
버전
"@version" 태그를 사용하여 주어진 코드의 버전을 문서화하십시오. 이 태그는 애플리케이션 버전을 참조하는 것이 아니라 실제로는 자체 버전을 참조한다는 점에 유의하십시오. 이 버전의 증가는 이 특정 코드가 변경되었음을 의미합니다.
/**
* @version 1.0.0
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
코드를 사용할 수 있게 된 이후로
"@since" 태그를 사용하여 다음 코드가 공개 API에 추가된 버전 번호를 문서화할 수 있습니다. 여기서 주목해야 할 중요한 것은 버전이 이제 애플리케이션 범위를 참조한다는 것입니다. 이것은 문서화된 특정 코드 블록으로 범위가 지정된 이전의 "@version" 태그와 대조됩니다.
/**
* @since 2.0.1
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
