[objective-c] doxygen으로 javadoc 스타일의 문서만들기

아이폰 앱 개발도중 라이브러리 또는 소스코드에 대한 문서가 필요한 경우가 있습니다. 이 경우 워드나 엑셀을 이용해 각 항목마다 일일히 설명을 작성할 수도 있지만 최소한의 노력으로 요구사항에 대응하기 위해 doxygen 이라는 도구를 사용할 수 있습니다. doxygen은 소스코드의 특정 주석을 활용해 웹페이지 또는 latex 같은 문서를 생성해 주는 도구입니다. c, c++, objective-c, c#, php, java, python 등 다양한 코드의 문서화에 사용될 수 있습니다.

doxygen gui 도구를 사용하면 매우 간단히 문서생성 작업을 할 수 있고 사용자의 입맛에 맞게 여러가지 전문가 옵션으로 커스터마이징도 가능합니다. doxygen 공식 페이지를 방문해 보시기 바랍니다.

먼저 doxygen이 인식하는 주석 블럭은 다양한 형태가 있습니다. 저는 아래와 같은 형태를 선호하지만 각자의 기호에 따라 선택하기 바랍니다.

/**
 * 문자열
 */

이 주석 블럭 안의 내용과 명령어에 따라 생성되는 문서의 내용이 달라지게 됩니다. 다음은 대표적인 지시자 입니다.

• brief: 클래스나 맴버 등에 대한 간단한 설명
• details: 자세한 설명을 서술
• author: 작성자
• version: 현재 버전
• date: 작성 날짜
• copyright: 저작권
• param: 파라미터
• return: 리턴 값

대략 이정도의 정보를 이용해 일반적인 javadoc 스타일의 문서를 만들 수 있습니다.

/** * MyObject 클래스에 대한 설명 * @brief 대략적인 설명 */ @interface MyObject: NSObject { /** * objectName에 대한 설명 */ NSString *objectName; /** * objectNumber에 대한 설명 */ NSUInteger objectNumber; } /** * objectArray에 대한 설명 */ @property (nonatomic, weak) NSMutableArray *objectArray; /** * methodWithName:objectNumber:에 대한 설명 * @param string 첫번째 매개변수에 대한 설명 * @param number 두번째 매개변수에 대한 설명 * @returns 리턴값에 대한 설명 */ - (BOOL)methodWithName:(NSString *)string objectNumber:(NSUInteger)number; @end

예제로 Example0001.h 헤더 파일을 작성해 보았습니다. 특별한 지시자를 쓰지 않아도 클래스나 맴버의 설명이 될 수 있으나 지시자를 같이 사용하면 문서상 우선순위에서 차이가 나타납니다.

#import "Example0001.h" /** * MyObject 구현에 대한 설명 */ @implementation MyObject /** * methodWithName:objectNumber:의 구현에 대한 설명 * @param string 첫번째 매개변수는 뭔지 설명 * @param number 두번째 매개변수는 뭔지 설명 * @returns 뭐가 리턴되는지 설명 */ - (BOOL)methodWithName:(NSString *)string objectNumber:(NSUInteger)number { return YES; } @end

간단한 구현 코드를 Example0001.m으로 만들어 봤습니다. 여기서는 헤더파일에 주석이 달려있지만 구현부에서 또 주석을 달았습니다. 선언 또는 구현 어느 한 쪽에만 주석을 달아도 문서작성에는 문제가 없지만 어떤 순서로 문서에 들어가는지 확인하기위해 작성해 보았습니다. 해당 프로젝트에 필요한 주석을 다 달았다면 doxygen을 실행하여 문서생성을 해줍니다. 그 결과는 다음과 같습니다.

보는 바와 같이 일반적으로 헤더파일에 작성한 주석이 문서의 앞에 위치하게 됩니다. 주석과 결과를 비교해 보고 각자의 필요에 따라 이용하면 됩니다.