TypeDoc는 최근 버전 0.27.7에서 주석 내에서 {@includeCode} 태그를 사용하여 외부 파일의 특정 부분을 참조할 수 있는 기능을 도입했습니다. 이는 코드 예제가 실제 테스트 코드에서 직접 가져와지므로, 문서화된 예제가 항상 최신 상태로 유지되고 정확성을 보장할 수 있습니다. 예를 들어, util.ts 파일의 함수 주석에 {@includeCode ./util_test.ts#utilFunc}를 사용하면, util_test.ts 내부의 utilFunc 영역에 해당하는 코드가 문서에 포함됩니다. 이러한 영역은 //#region과 //#endregion 주석을 사용하여 지정하며, Visual Studio Code에서도 지원하는 기능입니다.
이 기능의 주요 이점은 문서에 포함된 코드 예제가 실제로 테스트되었기 때문에 신뢰성이 높다는 것입니다. 이전에는 전체 파일만 포함할 수 있어 각 예제마다 별도의 파일이 필요했고, 이로 인해 문서에 불필요한 보일러플레이트 코드가 나타날 수 있었습니다. 이제는 특정 영역만 선택적으로 포함할 수 있어 문서가 더욱 간결해졌습니다.
실제 사용 예로 array.ts와 array_test.ts 파일이 있습니다. array.ts의 arrayToChunks 함수 주석에 {@includeCode ./array_test.ts#arrayToChunks}를 사용하여 테스트 코드의 관련 부분을 문서에 포함시켰습니다. 이를 통해 함수의 사용 방법을 명확하게 전달하면서도, 해당 예제가 실제로 테스트되었음을 보장합니다.
추가로, {@includeCode}에 대한 공식 문서와 관련 도구로는 Markdown 파일의 코드 예제를 검사하는 Markcheck, 그리고 JSDoc 예제를 doctest로 실행하는 jsdoctest 등이 있습니다.