jsDoc의 힘

많은 개발자들이 Javascript의 약한 타이핑에 대해 불평합니다(합당한 이유로). 그것이 우리가 Typescript의 등장을 목격한 이유입니다.
그러나 깔끔한 만큼 Typescript에는 몇 가지 주의 사항이 있습니다.

하드 타이핑

코드가 구문 분석되고 변경됨

추가 빌드 단계

학습할 새 구문

대부분의 경우 이들은 다루기 쉽거나 그냥 무시합니다. jsDoc이 정말 좋은 곳은 단점없이 약한 유형의 고통을 줄이고 테이블에 추가한다는 것입니다.

뭔데

먼저 이 자습서를 따라 재구성할 복잡한 예를 살펴보겠습니다.

/**
 * Nice little equine animal
 * @class
 * @extends Animal
 */
class Pony extends Animal {
    /**
     * Pony constructor
     * @param {String} name - This pony's name
     * @param {String} [color=Pony.colors.white] - This pony's color
     */
    constructor (name, color = Pony.colors.white) {
        super(name);
        this.color = color;
        /**
         * This pony's age
         * @type {Number}
         */
        this.age = 0;
    }

    /**
     * Make it run
     * @param {...String} through - Any number of field to run through
     * @example instance.run("field", "land");
     * @return {Pony} Itself
     */
    run (...through) {
        console.log("Run through ", ...through);
        return this;
    }

    /**
     * @typedef {Object} PonyColors
     * @prop {String} white - Pure light color
     * @prop {String} black - Dark color
     * @prop {String} foxy - Reddish color
     */
    /**
     * Get possible pony's colors
     * @static
     * @return {PonyColors}
     */
    static get colors () {
        return {
            white: "#fff",
            black: "#333",
            foxy: "#c57432",
        };
    }
}

그리고 여기 장점에 대한 데모가 있습니다(webstorm 사용). 자동 완성 툴팁을 자세히 살펴보십시오.



이제 단계별로 살펴보겠습니다.

설명

jsDoc의 가장 쉬운 사용은 함수나 클래스를 설명하는 것입니다.

/**
 * Nice little equine animal
 */
class Pony extends Animal {
    /**
     * Pony constructor
     */
    constructor (name, color = Pony.colors.white) {
        // ...
    }

    /**
     * Make it run
     */
    run (...through) {
        // ...
    }

    /**
     * Get possible pony's colors
     */
    static get colors () {
        // ...
    }
}

이제 여러분이 작성한 코드를 사용하는 사람은 누구나 각 함수 또는 클래스의 목적에 대한 정보를 갖게 됩니다.
IDE 또는 편집기에 따라 자동 완성이 시작될 때마다 툴팁에 표시됩니다.

매개변수

소개에서 JS의 변수 유형에 대해 이야기했습니다. 여기에서 문제를 해결할 것입니다.
JsDoc을 사용하면 함수에서 예상하는 유형(또는 유형)이 있는 매개변수를 지정할 수 있습니다. 그런 다음 호환되지 않는 유형의 매개변수를 제공하면 개발 환경에서 경고해야 합니다.

/**
 * Pony constructor
 * @param {String} name - A string
 * @param {String|Number} color - A string or a number
 */
constructor (name, color = Pony.colors.white) {
    // ...
}

동시에 변수 사용에 대한 빠른 설명을 제공할 수 있습니다.
매개변수가 선택 사항인 경우 대괄호로 묶고 해당하는 경우 기본값을 지정하십시오.

/**
 * Pony constructor
 * @param {String} name - This pony's name
 * @param {String} [color=Pony.colors.white] - This pony's color
 */
constructor (name, color = Pony.colors.white) {
    // ...
}

자동 완성에서 다시 한 번 그 효과를 볼 수 있습니다.

유형/콜백 정의

경우에 따라 클래스에서 래핑하지 않으려는 일부 데이터를 설명하기 위해 사용자 정의 유형을 정의해야 할 수 있습니다.

/**
 * @typedef {Object} PonyColors
 * @prop {String} white - Pure light color
 * @prop {String} black - Dark color
 * @prop {String} foxy - Reddish color
 */

이렇게 하면 객체의 각 항목에 유형과 설명을 첨부할 수 있습니다.



예상 매개변수의 경우에도 마찬가지입니다. 다음을 고려하십시오.

/**
 * @typedef {Object} CustomData
 * @prop {String} name - Cute name for you pony
 * @prop {String} [color=Pony.colors.white] - Color of its fur
 * @prop {Number} [age=0] - Years since its birth
 */
/**
 * Create a pony
 * @param {CustomData} data
 * @return Pony
 */
function ponyFactory (data) {
    // ...
}

CustomData 유형은 @typedef 블록에 설명되어 있습니다. 유형 정의는 @extends 태그를 사용하여 다른 이벤트를 확장할 수 있습니다. 정말 멋지네요 8)

함수가 콜백을 예상하는 경우(예: 일반적인 배열 트래버스) 이 콜백에 전달될 매개변수를 표시할 수 있습니다.

/**
 * @callback PonyCallback
 * @param {Pony} pony - A pony
 * @param {Number} index - Index of the pony
 * @param {Array<Pony>} list - List of all the ponies
 */
/**
 * Execute a function on each created pony
 * @param {PonyCallback} callback - Function called on each pony
 */
function herd (callback) {
    // ...
}

더 멀리

jsDoc 설명서에는 사용할 수 있는 lot of tags이 있습니다. 각 코드를 통해 사용자에게 코드를 더 잘 알릴 수 있습니다.

@return(반환된 유형 정의), @abstract(이 클래스는 인스턴스화하면 안 됨), @type(변수에 대한 유형 지정), @example(사용 예 표시)에 대한 존경하는 언급...

대부분의 경우 자신의 코드를 유지 관리하는 사람은 자신이라는 점을 기억하십시오. 실제로 작성하는 코드를 문서화하여 자신에게 서비스를 제공하는 것입니다.

마지막으로 모든 문서를 구문 분석하고 예를 들어 API를 문서화하기 위해 완전한 형식의 마크다운을 출력하는 numerous ways이 있습니다.