[펌] javadoc 유틸리티

Appendix II

 

javadoc 유틸리티

javadoc 유틸리티는 클래스들, 메소드들과 /** . . . */주석을 위한 소스파일을 분석한다.또한, API 문서와 같은 형태의 HTML 파일을 생성해낸다. 사실, API 문서는 자바 소스 파일에 대한 javadoc 의 결과이다.

만일 여러분의 소스 코드에 특별한 구별자인 /**로 시작하는 주석을 추가하면 여러분은 간단히 전문적으로 보이는 문서를 얻을 수 있다. 이 방법은 한 군데에 여러분의 코드와 문서를 저장하게 해주기 때문에 아주 좋은 방법이다. 전통적인 문서는 코드와 주석들이 분리되어 있는문제로 인해 고생하고 있다. 주석이 소스 파일로서 같은 파일 안에 존재하기 때문에 손쉽게내용을 갱신한 후 다시 javadoc 을 수행하기만 하면 된다.

우리는 corejava 패키지내의 파일들에 대해 /** 주석과 javadoc 을 사용했다. 여러분의 웹브라우저를 \CoreJavaBook\corejava\api\tree.html 에 위치시키면 친숙한 형태의corejava 문서를 볼 수 있을 것이다.

 

주석을 삽입하는 방법

javadoc 유틸리티는 다음의 기능에 대한 정보를 추출한다.

l  package

l  public 클래스

l  public interface

l  public 또는 protected 메소드

l  public 또는 protected 변수와 상수

여러분은 이러한 기능들 각각에 대한 주석을 제공할 수 있다.

각각의 주석은 설명하고자 하는 기능의 바로 위에 위치시킨다. 주석은 /**로 시작하여 */

끝을 낸다.

각 /* * . . . */ 문서화 된 주석은 태그를 따르는 자유 형태의 텍스트를 따른다. 태그

@author 또는 @param 와 같이 @로 시작한다.

자유 형태의 텍스트의 첫 문장은 요약문이다. Javadoc 유틸리티는 자동으로 이러한 문장을 가지는 요약 페이지를 생성한다.

자유 형태 텍스트에서 여러분은 이탤릭체를 위한 <i> . . . </i> , 타자체 폰트를 위한 <tt> . . . </tt> , 볼드체를 위한 <b> . . . </b> , 이미지를 포함하는 <img. . .>처럼 HTML 수식어를 사용할 수 있다. 그러나 여러분은 <h1>이나 <hr> 헤딩을 사용해서는 안 된다. 왜냐하면 이것들은 문서의 포맷팅과 충돌을 일으키기 때문이다.

----------------------------------------------------------------------

노트 : 만약 주석이 이미지(예를 들어, 사용자 인터페이스 구성요소의 다이어그램이나 이미

지)와 같은 다른 파일과의 링크를 포함한다면, 이러한 파일은 doc-파일로 이름 지위진 서브

디렉토리에 위치한다. javadoc 유틸리티는 이러한 모든 파일을 소스 디렉토리에서 문서 디

렉토리로 복사한다.

----------------------------------------------------------------------

 

일반적인 주석

다음의 태그들이 모든 문서화 주석에 지원된다.

@ since 텍스트

이 태그는 “since” 엔트리를 만든다. text 는 기능을 설명하는 버전을 기술하는 것이다.

@ deprecated 텍스트

이 태그는 더 이상 사용되지 않는 클래스, 메소드, 변수에 대하여 설명을 한다. text 는 제자리로 되돌린다(replacement). 예를 들어, @deprecated Use <tt> setVisible(true) </tt>@see 나 @link tags 를 사용하여 javadoc 문서의 연관된 일부분 또는 외부의 문서로 하이퍼링크되어 진다.

@see link

이 태그는 “See also” 섹션에서 하이퍼링크를 추가한다. 클래스와 메소드 두 가지를 모두사용할 수 있다. 이기서 link 는 아래의 하나이다.

l  package.class#feature label

l  <a href=”. . .”>label</a>

l  “text”

첫 번째 경우가 가장 유용한 경우이다. 클래스와 메소드, 변수의 이름을 주면 javadoc 은 문서에 하이퍼링크를 추가한다. 예를 들어, @see corejava.Console#readInt

(java.lang.String)는 corejava.Console 클래스의 readInt (String) 메소드에 링크를 추가한다. 패키지의 이름 혹은 패키지와 클래스의 이름을 모두 생략할 수 있다. 그러면,기능은 현재의 패키지나 클래스의 중심부에 있다.

메소드나 변수의 이름과 구분을 하기 위하여 #을 사용해야 함에 주의하여야 한다. 자바 컴파일러는 그 자체로, 패키지와 서브패키지, 클래스, 내부클래스, 메소드, 변수 사이의 구분자로서, 구간 문장의 다양한 의미를 추정하는 고도의 기술을 가지고 있다. 하지만 javadoc 유틸리티는 그렇게 똑똑하지 못하여 항상 도와 주어야 한다.

만약 < 문자 뒤에 @see 태그가 온다면 하이퍼링크를 명시하여야 한다. 여러분은 원하는 어떤URL 과도 링크를 할 수 있다. 예를 들어, @see <a href =

www.horstmann.com/corejava.html>The Core Java home page</a> 이러한 각 경우에, 링크를 고정시켜 보이게 하는 선택적인 label 을 지정할 수 있다. 레벨을잊었다면 사용자는 타겟 코드 이름이나 URL 을 볼 것이다.

“ 문자 다음에 @see 태그가 온다면 “see also” 절에 텍스트가 표시된다. 예를 들면, @see“Core Java 1.2 volume 2” 이다.하나의 기능에 대하여 다중 @see 태그를 추가 할 수도 있다. 하지만 이 모두는 반드시 함께있어야 한다.

원한다면 주석의 어디에라도 다른 클래스나 메소드에 하이퍼링크를 위치 시킬 수 있다. 주석의 어디에라도 {@link package.class#feature label} 형태의 특수형 태그를 추가 할 수 있다. 기능의 묘사는 @see tag 와 같은 룰을 따른다.

 

클래스와 인터페이스 주석

클래스 주석은 class 정의 바로 앞이면 어떠한 import 문 뒤에라도 올 수 있다.

태그에는 다음의 것들이 있다.

@author 이름

이 태그는 “author” 엔트리를 만든다. 여기에는 여러 명의 저자를 위한 복수개의 author태그를 사용할 수 있다. 그러나 그들은 모두 함께 선언돼야 한다.

@version