JSDoc 스크립트 주석

JSDoc 스타일 주석을 사용하면 사용자 정의 함수에 대해 코드 완성과 필수 인수를 코드 편집기에서 특정 방식으로 표시할 수 있습니다. 이러한 주석은 자동 완성 기능에 함수 사용 방법과 작성 방식을 알려주는 데 사용됩니다.

JSDoc 주석 생성

주석을 자동으로 생성하려면 Feather의 Quick Fixes 메뉴를 사용할 수 있습니다. 텍스트 커서를 함수 헤더에 놓고 Ctrl + Q를 누르거나 아이콘을 클릭하면 옵션이 표시됩니다.

함수 헤더 형식

일반적인 함수 헤더 형식은 다음과 같습니다:

• 함수 이름
• 함수 설명
• 함수가 받는 다양한 인수 목록

각 줄은 세 개의 슬래시 ///로 시작해야 하며, 이는 GameMaker에게 주석을 JSDoc 스타일로 파싱하도록 지시합니다. 또는 주석을 /**...*/로 감쌀 수도 있으며, /**는 별도의 줄에 있어야 합니다.

주석 식별자

주석 자체는 식별자(@로 시작)와 내용을 가져야 합니다. 사용 가능한 식별자는 다음과 같습니다:

인수나 반환 값의 타입을 지정하지 않으면 Feather는 함수 본문을 기반으로 자동으로 데이터 타입을 추정합니다.

예제

자신의 함수를 작성할 때 JSDoc이 어떻게 작동하는지 이해하기 위해 기본 예제를 살펴보겠습니다.

function is_same_object(_id, _obj) {
    if (_id.object_index == _obj) {
        return true;
    } else {
        return false;
    }
}

이 스크립트는 인스턴스가 주어진 객체와 동일한 object_index를 가지고 있는지 확인합니다. 호출 방법은 다음과 같습니다:

if (is_same_object(id, obj_Player)) {
    instance_destroy();
}

그러나 코드 편집기에 작성하면 인수 변수 이름(_id와 _obj)이 직접 표시되어 대부분의 경우 설명적이지 않습니다. JSDoc을 사용하여 사용자 정의 인수 이름과 설명을 정의할 수 있습니다.

/// @function                is_same_object(inst_id, object_id)
/// @description             Check if the given instance belongs to the given object.
/// @param {Id.Instance}     inst_id    The unique instance ID value of the instance to check.
/// @param {Asset.GMObject}  object_id  The object index to be checked against.
/// @return {Bool}
function is_same_object(_inst_id, _object_id) {
    return _inst_id.object_index == _object_id;
}

이제 프로젝트의 어디에서든 이 함수를 호출하면 JSDoc 주석에 입력된 새로운 인수 이름이 표시됩니다.

선택적 인수

인수 이름을 [] 대괄호로 감싸면 선택적임을 나타낼 수 있습니다. 그러면 코드 편집기는 최소 필수 인수와 총 인수 수 사이의 어떤 수의 인수를 기대합니다.

예를 들어 다음 함수를 보십시오:

/// @function    animate_position(end_x, end_y, start_x, start_y)
/// @desc        Animates the instance to ending point, from optional starting point
/// @arg end_x
/// @arg end_y
/// @arg [start_x]
/// @arg [start_y]
function animate_position(x1, y1, x2, y2) {
    // Function code
}

start_x와 start_y 인수는 선택적으로 표시되므로 코드 편집기는 이제 2에서 4개의 인수를 기대합니다.

여러 함수에 대한 JSDoc 주석

스크립트에는 여러 함수가 있을 수 있으므로 각 함수 선언 전에 JSDoc 주석을 추가할 수 있습니다.