자바를 특별하게 만드는 JavaDoc.

티스토리 메뉴 펼치기 댓글수4

Dev Center/JAVA start

자바를 특별하게 만드는 JavaDoc.

seanhigher
댓글수4
자바는 그 자체가 클래스로 되어있는 언어이다. 클래스에 대해서 많이 알수록 더 많은 가능성을 가지게 되는 것이다. 또한 이러한 것들은 자바 API라는 문서를 통해서 더욱 쉽게 접근할 수 있다. 그럼 자바 API는 누가 만들까? 자바를 관리하는 썬사에서 하는것일까? 보통 표준의 것은 그렇다. 하지만, 여러분들도 만들 수 있다. 비록 모든 사람들이 인정하지는 않지만...!



자바에서의 주석처리문.
javadoc 에 대해서 말하기 전에 먼저 알아야 할 것이 자바 안에서의 주석문 처리방식이다. 자바에서는 기본적으로 두가지 방식으로 주석문을 처리하고 있다. 첫번째는 '/* 내용 */' 과 같은 형식으로 여러줄의 주석문을 처리할때 유용하게 사용할 수 있다.

/*
여기서부터는 주석입니다.
만든이 : Devist
날짜 : 2010년 06월 29일
*/

두번째 방식으로는 한줄의 간단한 주석이 필요할때 사용하는 방식인데, '//'의 뒤에 주석문의 내용을 적는 것이다.

int x = 10     // 변수 x 는 OO을 의미한다.

주석문은 프로그램을 작성하는데 있어서 매우 중요한 역할을 한다. 짧은 프로그램에서는 상관이 없겠지만, 점점 긴 프로그램이 될 수록 자신이 만들어 놓고도 무슨내용이었지 하면서 고민을 하는 경우가 종종 생기곤 하기때문에 이런 문제를 미연에 방지하기 위해서 주석은 필수적이라고 할 수 있다. 위의 두가지 방법만 알고 있어도 주석을 표현하는데는 부족함이 없을 것이다. 하지만, 자바에서는 자바만의 특별한 주석문이 있다.


/** */ javadoc 를 만드는 주석문
우리가 자바를 사용하면서 쉽게 접할 수 있는 JAVA API 문서는 javadoc 로 만들어진 문서라고 볼 수 있다. 그렇다면 javadoc 는 개발자의 의도를 알아차리고 도움말을 자동으로 만들어 줄만큼 똑똑한 것일까? 물론 그것은 아니다. 하지만, 개발자가 약간의 정보를 제공한다면 JAVA API 와 같은 자신만의 좋은 API를 만들 수 있다. 도움말을 만들기 위한 주석을 제대로 표현하기 위해서는 몇가지 조건에 맞추어서 주석을 달아야 한다. 만약 규칙을 지키지 않는다면 원하지 않는 전혀 다른 형태의 도움말이 만들어 질 수 있을 것이다.

/**
 * 연습용 클래스 입니다
 * @author Devist
 */
public class Test {
/**
 * 출력용 메소드 입니다.
 * @param String str 문자
 * @param int x 기본 변수
 * @return String re OK or Failed
 */
    public static disp() {
        System.out.println("display);
    }
}

도움말을 만들기 위한 주석문의 사용은 위와 같다. 기본적으로 클래스나 메소드 위에 '/** */' 과 같은 표시가 있다면 그 클래스(메소드)에 대한 설명으로 인식하고 해당 영역에 대한 도움말을 작성하게 된다. 그리고 주석문의 앞에는 항상 '*' 마크가 있어야 인식이 가능하다. 그리고 이 모든 주석들은 자바 API와 같이 html 형태로 생성되기 때문에 기능을 좀더 잘 표현하고 싶다면 태그를 사용해서 좀더 꾸미는 것이 가능하다. 앞에 골뱅이(@)로 표시되어 있는것들은 각 이미 지정된 예약어로써의 기능을 가지고 있다. '@ 파라메터 설명' 과 같은 형태로 쓰이며 각 구분은 공백으로 이루어지며, 파라메터로 쓰이는 단어와 의미는 다음과 같다.

@author 개발자
@exception 메소드에서의 예외 확인
@param 메소드의 매개변수
@return 메소드의 반환값
@see 다른 주제에 관한 링크 지정
@serial 직렬화 필드
@since 릴리즈 기록
@throws 메소드에서의 예외
@version 클래스의 버전

위에서 설명한 파라메터 외에서 몇가지의 파라메터들이 더 사용되고 있다. 좀더 자세한 사항을 알아보고 싶다면 http://java.sun.com/j2se/javadoc/index.html  사이트에서 확인이 가능하다.


javaDoc 만들기.
위와 같이 주석을 작성한다고 해서 자동으로 javaDoc 문서가 만들어지는 것은 아니다. 자바를 컴파일 할때와 비슷한 방식으로 컴파일을 해주어야 한다. 먼저 위의 방식에 맞추어서 프로그램 소스와 주석문을 작성하도록 한다. 다 준비가 되었다면 왼쪽 파일 트리에서 프로젝트를 선택한 후 오른쪽 버튼을 클릭하도록 한다.


그림1. Export 메뉴

나타난 메뉴에서 'Export' 메뉴를 선택하도록 한다. Export' 메뉴를 선택하면 어떠한 형식으로 Export 를 할것인지에 대해서 나오게 되는데, 'Java' -> 'JavaDoc' 를 차례로 선택하도록 한다. 그러면 아래와 같은 메뉴가 나오게 되는데, 기본적인 설정으로 놔두게 되면 프로젝트가 생긴 폴더에 'doc' 폴더가 생기고 그곳에 DOC 문서가 생성된다. 기본설정으로 두고 'Finish' 버튼을 누르도록 한다.


그림2. Java Doc 생성

'Finish' 버튼을 클릭하고 나면 자동으로 문서가 생성되는 것을 볼 수 있다. 콘솔창에서 무언가 실행되는것이 마쳐진 후, 프로젝트 폴더를 탐색해 보면  기본적으로 있는 'src' 와 'bin' 폴더 이외에 'doc' 폴더가 새로 생겨 있는 것을 확인할 수 있다. 이 'doc' 폴더를 보면 'index.html' 파일이 있는데 이것이 바로 생성한 JAVA DOC 문서이다. 앞으로도 더 문서를 추가한다면 이 문서안에 추가적으로 생성되는것을 볼 수 있다.


그림3. JavaDoc 문서

자바DOC 문서를 만드는 것은 어떻게 보면 굉장히 귀찮은 일일 수 도 있다. 하지만, 자신이 어렵게 만든 프로그램 소스를 다른 사람들이 더 잘 이요할 수 있는 가이드 라인이 되어줄 것이다. 서로의 것을 공유할때 그것은 단순히 더해지는 것에서 그치는 것이 아니라 그 이상의 능력을 발휘하게 될 것이다.

맨위로