JavaDoc 을 이용한 Java API 문서 생성하기

JavaDoc.exe 는 Java 소스 코드로 부터 HTML 형식의 API Documentation 문서를 생성해 주는, SUN Microsystems 에서 만든 문서 생성기이다.
다음 사이트를 참조하기 바란다.
1. JavaDoc Homepage : http://java.sun.com/j2se/javadoc/
2. Wikipedia : http://en.wikipedia.org/wiki/Javadoc
3. 개인 블로그 : http://blog.naver.com/kvivaldi/60009671313
이번 아티클에서는 JavaDoc 을 이용해서 간단하게 문서를 생성하는 방법을 살펴보고, 다음글에서 Eclipse 에서의 생성법, 그리고 Doxygen 툴을 사용해서 생성하는 방법들을 살펴보도록 하자.

먼저 간단하게 에디터를 사용해서 아래의 문서를 작성해 보았다.

위의 문서에서 보듯이 간단하게 현재 날짜 및 시간을 출력하는 프로그램소스이다. 클래스 설명부분은 클래스 소스 위에, 메소드 설명부분은 메소드 위쪽에 기술하면 된다. 필요한 notation 은 아래에 따로 설명하도록 하겠다. 일단 저장하고 컴파일해서 문법에 이상이 있는지 없는지 살펴보자.

JavaDoc.exe 을 사용하는 방법은 의외로 간단하다. 도스모스(Windows Platform)이나 터미널환경(Linux)에서 위의 그림처럼 명령어에 필요한 옵션을 넣은 다음 실행명령을 내리면 된다. 위 명령어에서는, -author 즉, 저자를 표기하고, -version 버전을 표시하며, 문서 생성 위치는 -d 옵션을 이용해서 현재 아래의 docs라는 디렉토리에 생성하라는 것이다. 여기서 Windows Platform 에서는 아래와 같이 명령어를 넣어야 한다.

C:＼JavaRoom>javadoc -author -version -d .＼docs JavaDocDemo.java

잘 알겠지만, Windows 와 Linux/Unix 의 경로 지정차이다. '＼' 이든, '/' 이든 플랫폼에 맞게 경로를 지정하면 된다.
자 이와같이 명령어를 내리면 docs 디렉토리에 HTML 문서들이 생성됐을 것이다. 살펴보자.

docs 디렉토리에 가니 index.html 파일이 있고, 웹브라우저를 이용해서 파일을 열었더니 위의 그림과 같이 생성되었다. 생성자체는 별로 어려움이 없다. 필요한 옵션을 아래와 같다.

JavaDoc 주석은 /** 로 시작해서 */ 로 끝나게 되며 각 라인은 * 로 시작해야 한다. 아래는 필요한 JavaDoc 주석의 태그들이다. 당연히 자바니까 대소문자 구별한다.

1. 클래스와 인터페이스에서
@see 태그 : 이 태그를 이용하면 우리가 API에서 다른 패키지를 보고자 할 때 넘어가는 하이퍼링크를 생성해 준다. JavaDoc 빌드시 See also 란 항목으로 나타난다. 하지만, 올바른 하이퍼 링크인지는 JavaDoc이 확인하지 않는다.
     ex) 
       @see 클래스 이름
       @see 패키지가 지정된 클래스면
       @see 패키지가 지정된 클래스명#메소드

@version : 해당 클래스의 버전정보를 나타내고자 할 떄 사용된다.   빌드시 -version  옵션 필요.
     ex) @version 1.2

@author : 작성자 정보를 넣는다. 가령, 이름이나 EMail 주소 같은... 역시 빌드시 -author 옵션 필요
     ex) @author JavaMan

@since : 태그를 가진 객체의 추가 시기를 기술한다. 빌드시 별다른 옵션없이 사용하며, 포함하고 싶지 않으면 -nosince 를 사용하면 된다.

2. 메소드에서
@param : 메소드의 매개변수에 대한 설명을 기술한다. 
@return : 메소드의 반환될 값을 설명한다. 
@exception : 메소드에서 발생할 수 있는 예외를 설명한다. @throws 과 같다. 
@deprecated : 혹 사용버전과 이전버전과의 호환성 문제가 발생할 것에 대비해서 사용금지정보를 설명한다. 문서에 포함시키지 않으려면 -nodeprecated옵션을 주면 된다.