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
'JAVA > JSE' 카테고리의 다른 글
[펌] JAVA application 성능향상.. (0)
2004.10.07
[펌 http://raytrust.pe.kr/] signed applet (0)
2004.09.06
[nio] 기초 정리 잘된곳 (0)
2004.08.09
[펌] 나만의 자바 컴포넌트를 만들자 (0)
2004.04.01
[펌] 블랙박스에서 엔터프라이즈 까지, Part 3 : JMX 통합 (0)
2004.03.29