적절한 코드 문서화는 소프트웨어 개발에서 중요하지만 종종 간과되는 측면입니다. 개발자로서 깨끗하고 효율적인 코드를 작성하는 데는 익숙하지만 좋은 문서를 작성하는 데는 경험이 부족할 수 있습니다.

좋은 문서는 팀의 다른 구성원이든 나중에 본인이든 코드를 사용하여 작업하는 모든 사람에게 유용합니다. 특정 방식으로 무언가를 구현한 이유나 특정 기능이나 API를 사용하는 방법을 설명할 수 있습니다.

JavaScript 개발자에게 JSDoc은 코드 문서화를 시작하는 좋은 방법입니다.

JSDoc이란 무엇입니까?

코드를 문서화하는 것은 복잡하고 지루할 수 있습니다. 그러나 더 많은 사람들이 “코드로서의 문서” 접근 방식의 이점을 인식하고 있으며 많은 언어에는 프로세스를 자동화하는 데 도움이 되는 라이브러리가 있습니다. 간단하고 명확하며 간결한 문서화를 위해. Go 언어에 코드에서 문서화를 자동화하는 GoDoc이 있는 것처럼 JavaScript에도 JSDoc이 있습니다.

JSDoc은 JavaScript 소스 코드의 특수 주석을 해석하고, 이러한 주석을 처리하고, 맞춤형 문서를 생성하여 문서를 생성합니다. 그런 다음 이 문서를 액세스 가능한 HTML 형식으로 제공합니다.

이렇게 하면 코드 내에 문서가 유지되므로 코드를 업데이트할 때 문서를 쉽게 업데이트할 수 있습니다.

JSDoc 설정

JSDoc의 제작자는 JavaScript 프로젝트에서 JSDoc을 쉽게 시작하고 설정할 수 있도록 만들었습니다.

JSDoc을 로컬로 설치하려면 다음을 실행하세요.

 npm install --save-dev jsdoc

그러면 프로젝트에 개발 종속성으로 라이브러리가 설치됩니다.

JSDoc을 사용하려면 소스 코드 내에서 특수 구문 주석을 사용해야 합니다. 모든 문서 주석은 /** 및 */ 마커 안에 작성합니다. 이 안에는 정의된 변수, 함수, 함수 매개변수 등을 설명할 수 있습니다.

예를 들어:

 
 * Gets User by name.
 * @param {string} name - The name of the User
 * @returns {string} User
 */

function getUser(name) {
  const User = name;
  return User;
}

@param 및 @returns 태그는 JSDoc이 코드를 설명하기 위해 지원하는 많은 특수 키워드 중 두 가지입니다.

  파일을 온라인으로 전송할 때 대용량 업로드 일시 중지 및 재개

이 코드에 대한 문서를 생성하려면 npx jsdoc와 JavaScript 파일 경로를 차례로 실행하세요.

예를 들어:

 npx jsdoc src/main.js

JSDoc을 전역적으로 설치한 경우 npx 플래그를 생략하고 다음을 실행할 수 있습니다.

이 명령은 프로젝트 루트에 out 폴더를 생성합니다. 폴더 안에는 문서 페이지를 나타내는 HTML 파일이 있습니다.

문서를 호스팅할 로컬 웹 서버를 설정하거나 브라우저에서 out/index.html 파일을 열어 문서를 볼 수 있습니다. 다음은 기본적으로 문서 페이지가 어떻게 보이는지에 대한 예입니다.

JSDoc 출력 구성

구성 파일을 생성하여 JSDoc의 기본 동작을 변경할 수 있습니다.

이렇게 하려면 conf.js 파일을 만들고 이 파일 안에 JavaScript 모듈을 내보내세요.

예를 들어:

 module.exports = {
  source: {
    includePattern: ".+\\\\.js(doc|x)?$",
    excludePattern: ["node_modules"],
  },
  recurseDepth: 5,
  sourceType: "module",
  opts: {
    template: "path/to/template",
    destination: "./docs/",
    recurse: true,
  },
};

구성 파일 내부에는 다양한 JSDoc 구성 옵션. 템플릿 옵션을 사용하면 템플릿을 사용하여 문서의 모양을 사용자 정의할 수 있습니다. JSDoc 커뮤니티는 다양한 기능을 제공합니다. 템플릿 당신이 사용할 수 있습니다. 이 패키지를 사용하면 자신만의 맞춤형 템플릿을 만들 수도 있습니다.

생성된 문서의 위치를 ​​변경하려면 대상 구성 옵션을 디렉터리로 설정하세요. 위의 예에서는 프로젝트 루트에 docs 폴더를 지정합니다.

구성 파일로 JSDoc을 실행하려면 다음 명령을 사용하십시오.

 jsdoc -c /path/to/conf.js

이 명령을 더 쉽게 실행하려면 package.json 파일 내에 스크립트 항목으로 추가하세요.

 "scripts": {
    "dev": "nodemon app.js",
    "run-docs": "jsdoc -c /path/to/conf.js"
 },

이제 터미널 내에서 npm 스크립트 명령을 실행할 수 있습니다.

JSDoc으로 생성된 문서의 예

다음은 더하기 및 빼기 메소드가 있는 간단한 산술 라이브러리입니다.

다음은 잘 문서화된 JavaScript 코드의 예입니다.

 
 * A library for performing basic arithmetic operations.
 * @module arithmetic
 */
module.exports = {
    
     * Adds two numbers.
     * @param {number} a - The first number.
     * @param {number} b - The second number.
     * @return {number} The sum of the two numbers.
     * @throws {TypeError} If any of the arguments is not a number.
     *
     * @example
     * const arithmetic = require('arithmetic');
     * const sum = arithmetic.add(5, 10);
     * console.log(sum);
     */
    add: function(a, b) {
        if (typeof a !== 'number' || typeof b !== 'number') {
            throw new TypeError('Both arguments must be numbers.');
        }

        return a + b;
    },

    
     * Subtracts the second number from the first number.
     * @param {number} a - The number to subtract from.
     * @param {number} b - The number to subtract.
     * @return {number} The result of the subtraction.
     * @throws {TypeError} If any of the arguments is not a number.
     *
     * @example
     * const arithmetic = require('arithmetic');
     * const difference = arithmetic.subtract(10, 5);
     * console.log(difference);
     */
    subtract: function(a, b) {
        if (typeof a !== 'number' || typeof b !== 'number') {
            throw new TypeError('Both arguments must be numbers.');
        }

        return a - b;
    }

    
};

JSDoc 주석은 다음을 포함하여 라이브러리와 해당 메서드에 대한 명확하고 포괄적인 설명을 제공합니다.

  • 도서관과 그 목적에 대한 설명입니다.
  • 유형 및 간략한 설명을 포함한 각 메소드의 매개변수입니다.
  • 각 메서드가 반환하는 값과 유형입니다.
  • 각 메서드에서 발생할 수 있는 오류와 이를 발생시키는 조건.
  • 각 방법을 사용하는 방법의 예입니다.
  Reddit에서 섀도우밴을 당했는지 확인하는 방법

또한 주석에는 이 파일이 모듈임을 나타내는 @module 태그와 각 메서드에 대한 코드 예제를 제공하는 @example 태그가 포함되어 있습니다.

개발자 코드를 올바른 방법으로 문서화하기

보시다시피 JSDoc은 JavaScript 코드 문서화를 시작하는 데 매우 유용한 도구입니다. 간편한 통합을 통해 코드를 작성할 때 빠르고 자세한 문서를 생성할 수 있습니다. 작업 공간에서 바로 문서를 유지 관리하고 업데이트할 수도 있습니다.

그러나 JSDoc의 자동화만큼 유용한 만큼, 고품질 문서를 ​​생성하려면 특정 지침을 준수해야 합니다.

x