====== 스크립트 도움말 가이드 ====== 이 화면은 xFrame5 개발툴에서 각 화면 및 공통 모듈에 제공하는 "스크립트 도움말 파일 생성" 대한 예시 화면이다. 도움말 작성 문법은 JSDoc 규약을 기준으로 생성된다. (화면 스크립트 소스 및 주석 참조) (https://jsdoc.app/index.html) 공통 모듈에 대한 도움말 파일은 솔루션 설치 디렉토리 하위 apidoc\common_module 디렉토리에 생성된다. 개별 화면에에 대한 도움말 파일은 솔루션 설치 디렉토리 하위 apidoc 디렉토리 하위에 화면 경로 디렉토리에 생성된다. ===== 예시 ===== 템플릿 위치: /STUDIO/USAGE/usage_jsdoc 템플릿 파일 * [[xf5projecthome>template/screen/STUDIO/USAGE/usage_jsdoc.xml|usage_jsdoc.xml]] * [[xf5projecthome>template/screen/STUDIO/USAGE/usage_jsdoc.js|usage_jsdoc.js]] * [[xf5projecthome>template/template.html?xframe_screen_url=/STUDIO/USAGE/usage_jsdoc|새창으로 실행]] echo ''; echo ''; echo ''; ==== 화면 스크립트 ==== /** * 이 모듈은 JSDoc 기반의 스크립트 주석 작성 정보를 제공하기 위한 모듈
* 반드시 module 태그를 사용하여 파일 이름을 지정해야 함
* 도움말 주석 내용에 강제 개행을 해기 위해서는 위행의 맨 마작막처럼 br 태그 사용함
* 도움말 내용은Members, Methods, Type Definitions, Events 영역 순서로 생성되며, * 각 영역 내에 알파벳 순으로 내용이 정렬되어 도움말이 작성됨. * @module usage_jsdoc * @version 1.1 현재 버전 정보 * @since 0.9 생성되기 시작한 버전 * @author 홍명준 */ /** * 도움말 작성 제외 대상에는 주석 작성 예시 (private 태그를 정의) * 주석은 작성하나 도움말 문서에서 제외하기 위해서는 @private 태그 정의 * @private */ function jsdoc_func_private() { } /** * 멤버 상수 주석 작성 에시 * @const * @type {string} */ const const_variable = "20210113"; /** * 멤버 변수 주석 작성 예시 * @member * @type {string} */ var member_variable = "20210113"; /** * 이벤트 및 이벤트 파라미터 주석 작성 예시
* 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 오브젝트형 이젠트 파라미터 */ /** * 이벤트 및 이벤트 파라미터 주석 작성 예시
* @event on_event_return * @param {string} event_param_string 문자열 이벤트 파리미터 * @param {number} event_param_number 숫자 이벤트 파리미터 * @param {Object} event_param_object 오브젝트형 이젠트 파라미터 * @returns {*} 모든 형의 값을 리턴 */ /** * 함수 파라미터에 대한 주석 작성 방벱에 대한 예시
* https://jsdoc.app/tags-param.html
* The @param tag provides the name, type, and description of a function parameter.
* The @param tag requires you to specify the name of the parameter you are documenting.
* 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) { } /** * 함수 사용 예시 주석 작성 방벱 예시
* https://jsdoc.app/tags-example.html#examples * @example Example 1 usage of jsdoc_func_example. * // returns "abc" * jsdoc_func_example("abc"); * @example Example 2 usage of jsdoc_func_example. * // returns 123 * jsdoc_func_example(123); */ function jsdoc_func_example(func_param) { return func_param; } /** * 함수 리턴값 주석 작성 방벱 예시
* https://jsdoc.app/tags-returns.html * @returns {*} 모든 형의 값을 리턴 */ function jsdoc_func_return_any_type() { return null; } /** * 함수 리턴값 주석 작성 방벱 예시
* https://jsdoc.app/tags-returns.html * @returns {number} 숫자형 값을 리턴 */ function jsdoc_func_return_number() { return 1; } /** * 함수 리턴값이 선택적인 경우에 대한 주석 작성 예시
* @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; } } /** * 함수 리턴값이 오브젝트 형태인 경우 주석 작성 예시
* @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에 정의된 오브젝트인 경우 주석 작성 방벱 예시
* @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; }