이 문서에서는 XE core code에 주석을 어떻게 달 것인지를 의논하고 정의합니다.
모든 주석은 영어로 씁니다.
Doxygen
Doxygen에서 문서를 만들 수 있는 포맷을 따라서 주석을 달도록 합니다.
Doxygen Commands : http://www.stack.nl/~dimitri/doxygen/commands.html#cmdbrief
각 command는 역슬래시(\) 대신 @표시로 사용합니다. ex) @brief Comments test
함수 (function)
각 function은 다음에 해당하는 command들을 표시합니다.
- param : parameters - http://www.stack.nl/~dimitri/doxygen/commands.html#cmdparam
- [in] : input
- [out] : output
- return : return값에 대한 설명 - http://www.stack.nl/~dimitri/doxygen/commands.html#cmdreturn
- remarks (optional) : 따로 추가적인 내용 설명이 필요한 경우
- brief : 간단한 function의 기능 설명
예) debugPrint 함수
/**
* @brief prints debug messages
* @param
in debug_output target object to be printed
* @param
in display_line boolean flag whether to print seperator (default:true)
* @return none
*/
변수 (variable)
전역변수 혹은 클래수 내부의 변수는 변수 선언 뒤에 슬래쉬 세개 + < (///<)를 붙인 뒤에 간단한 설명을 적습니다.
ex) var $error = 0; ///< ErrorCode
클래스 (class)
각 class에는 다음의 command를 입력합니다.
- class : class 이름
- brief : class에 대한 간단한 설명
- remarks (optional)
- author, date (optional)
일반적인 주석
Doxygen comment를 제외한 코드에 대한 설명은 슬래쉬 두개(//) 를 이용하되, 긴 설명이 필요한 경우에는 하나의 함수로 뽑아서 doxygen comment로 달도록 합니다.