스크립트 도움말 가이드
이 화면은 xFrame5 개발툴에서 각 화면 및 공통 모듈에 제공하는 “스크립트 도움말 파일 생성” 대한 예시 화면이다.
도움말 작성 문법은 JSDoc 규약을 기준으로 생성된다. (화면 스크립트 소스 및 주석 참조) (https://jsdoc.app/index.html)
공통 모듈에 대한 도움말 파일은 솔루션 설치 디렉토리 하위 apidoc\common_module 디렉토리에 생성된다.
개별 화면에에 대한 도움말 파일은 솔루션 설치 디렉토리 하위 apidoc 디렉토리 하위에 화면 경로 디렉토리에 생성된다.
예시
화면 스크립트
/**
* 이 모듈은 JSDoc 기반의 스크립트 주석 작성 정보를 제공하기 위한 모듈<br>
* 반드시 module 태그를 사용하여 파일 이름을 지정해야 함<br>
* 도움말 주석 내용에 강제 개행을 해기 위해서는 위행의 맨 마작막처럼 br 태그 사용함<br>
* 도움말 내용은Members, Methods, Type Definitions, Events 영역 순서로 생성되며,
* 각 영역 내에 알파벳 순으로 내용이 정렬되어 도움말이 작성됨.
* @module usage_jsdoc
* @version 1.1 현재 버전 정보
* @since 0.9 생성되기 시작한 버전
* @author 홍명준 <mjhong@softbase.co.kr>
*/
/**
* 도움말 작성 제외 대상에는 주석 작성 예시 (private 태그를 정의)
* 주석은 작성하나 도움말 문서에서 제외하기 위해서는 @private 태그 정의
* @private
*/
function jsdoc_func_private() { }
/**
* 멤버 상수 주석 작성 에시
* @const
* @type {string}
*/
const const_variable = "20210113";
/**
* 멤버 변수 주석 작성 예시
* @member
* @type {string}
*/
var member_variable = "20210113";
/**
* 이벤트 및 이벤트 파라미터 주석 작성 예시<br>
* https://jsdoc.app/tags-event.html
* @event on_event_param
* @param {string} event_param_string 문자열 이벤트 파리미터
* @param {number} event_param_number 숫자 이벤트 파리미터
* @param {Object} event_param_object 오브젝트형 이젠트 파라미터
*/
/**
* 이벤트 및 이벤트 파라미터 주석 작성 예시<br>
* @event on_event_return
* @param {string} event_param_string 문자열 이벤트 파리미터
* @param {number} event_param_number 숫자 이벤트 파리미터
* @param {Object} event_param_object 오브젝트형 이젠트 파라미터
* @returns {*} 모든 형의 값을 리턴
*/
/**
* 함수 파라미터에 대한 주석 작성 방벱에 대한 예시<br>
* https://jsdoc.app/tags-param.html<br>
* The @param tag provides the name, type, and description of a function parameter.<br>
* The @param tag requires you to specify the name of the parameter you are documenting.<br>
* You can also include the parameter's type, enclosed in curly brackets, and a description of the parameter.
*
* @param {*} param_any_type 모든 유형 파라미터
* @param {boolean} param_boolean 불린형 파라미터
* @param {number} param_number 숫자 파라미터
* @param {string} param_string 문자열 파라미터
* @param {Object} param_object 오브젝트 파라미터
* @param {Object} param_object_property 아래와 같이 속성을 가지는 오브젝트 파라미터
* @param {string} param_object_property.name object_property_param 오브젝트의 name 속성
* @param {string} param_object_property.department object_property_param 오브젝트의 department 속성
* @param {Object[]} param_object_array 아래와 같이 속성을 가지는 오브젝트 배열 파라미터
* @param {string} param_object_array.name param_object_array 오브젝트의 name 속성
* @param {string} param_object_array.department param_object_array 오브젝트의 department 속성
* @param {Array} param_array 배열 파라미터
* @param {string[]} param_array_string 문자열 배열 파라미터
* @param {(string|number|boolean)} param_string_number_boolean 문자열 또는 숫자 또는 불린형 파라미터 ('|' 문자로 구분, 괄호로 감쌈)
* @param {(string|null)} param_string_null 문자열 또는 null 파라미터
* @param {number} [param_option] 옵션 파라미터
* @param {number} [param_option_default_value=1] 파라미터 값 미 지정시 기본값(1)을 가지는 옵션 파라미터
* @param {?number} param_null_or_number null 이거나 숫자인 파라미터
* @param {!number} param_not_null_number null이 될 수 없는 파라미터
* @param {...number} param_variable_number 여래개의 파라미터를 받아들이는 함수를 지정하는 방식
*/
function jsdoc_func_param(param_any_type, param_boolean, param_number, param_sting,
param_object, param_object_property, param_object_array,
param_array, param_array_sting,
param_string_number_boolean, param_string_null,
param_option, param_option_default_value,
param_null_or_number, param_not_null_number, param_variable_number) {
}
/**
* 함수 사용 예시 주석 작성 방벱 예시<br>
* https://jsdoc.app/tags-example.html#examples
* @example <caption>Example 1 usage of jsdoc_func_example.</caption>
* // returns "abc"
* jsdoc_func_example("abc");
* @example <caption>Example 2 usage of jsdoc_func_example.</caption>
* // returns 123
* jsdoc_func_example(123);
*/
function jsdoc_func_example(func_param) {
return func_param;
}
/**
* 함수 리턴값 주석 작성 방벱 예시<br>
* https://jsdoc.app/tags-returns.html
* @returns {*} 모든 형의 값을 리턴
*/
function jsdoc_func_return_any_type() {
return null;
}
/**
* 함수 리턴값 주석 작성 방벱 예시<br>
* https://jsdoc.app/tags-returns.html
* @returns {number} 숫자형 값을 리턴
*/
function jsdoc_func_return_number() {
return 1;
}
/**
* 함수 리턴값이 선택적인 경우에 대한 주석 작성 예시<br>
* @returns {(string|boolean)} 문자열 또는 불린 값을 리턴
* @returns {string} param_type이 문자열인 경우에 문자열 리턴
* @returns {number} param_type이 문자열이 아닌 경우에 불린형 리턴
*/
function jsdoc_func_return_number_or_boolean(param_type) {
if (param_type == "string") {
return "string";
}
else {
return true;
}
}
/**
* 함수 리턴값이 오브젝트 형태인 경우 주석 작성 예시<br>
* @returns {Object} 아래의 속성을 가지는 return_object 오브젝트 리턴
* @property {string} return_object.prop_inner_a return_object 오브젝트의 prop_inner_a 속성 설명
* @property {string} return_object.prop_inner_b return_object 오브젝트의 prop_inner_b 속성 설명
*/
function jsdoc_func_return_object() {
var return_object = {
prop_inner_a: "prop_inner_a",
prop_inner_b: "prop_inner_b"
};
return return_object;
}
/**
* @typedef {Object} typedef_inner_object
* @property {string} prop_inner_a typedef_inner_object 오브젝트의 prop_inner_a 속성
* @property {string} prop_inner_b typedef_inner_object 오브젝트의 prop_inner_b 속성
*/
/**
* @typedef {Object} typedef_object
* @property {string} prop_a typedef_object 오브젝트의 prop_a 속성
* @property {string} [prop_b] typedef_object 오브젝트의 prop_b 옵션 속성
* @property {typedef_inner_object} prop_inner_object typedef_object 오브젝트의 prop_inner_object 속성
*/
/**
* 함수 리턴값이 typedef에 정의된 오브젝트인 경우 주석 작성 방벱 예시<br>
* @returns {typedef_object} typedef_object 오브젝트를 리턴(typedef_object 정의 참조)
*/
function jsdoc_func_return_object_typedef() {
var typedef_object = {
prop_a: "prop_a",
prop_b: "prop_b",
typedef_inner_object: {
prop_inner_a: "prop_inner_a",
prop_inner_b: "prop_inner_b"
}
};
return typedef_object;
}