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> 헤딩을 사용해서는 안 된다.

왜냐하면 이것들은 문서의 포맷팅과 충돌을 일으키기 때문이다.

 

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

Note : 만약 주석이 이미지(예를 들어, 사용자 인터페이스 구성요소의 다이어그램이나
          이미지)와 같은 다른 파일과의 링크를 포함한다면, 이러한 파일은 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 = The">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 텍스트
이 태그는 version 엔트리를 만든다. text 는 최신 버전의 어떠한 것으로도 기술 될 수 있다.

여기서 클래스 주석의 예를 하나 보자.

/**

A class for formatting numbers that follows <tt>printf</tt>

conventions. All options of the C <tt>printf</tt> function are

supported.

@version 1.01 15 Feb 1996

@author Cay Horstmann

@see Kernighan and Ritchie, The C Programming Language, 2nd

ed.”

*/

 

 

 

[ 메소드 주석 ]

각 메소드 주석은 설명하는 메소드의 시그니처(signature)에 선행하여야 한다.
일반적인 목적의 태그에 추가하기 위하여는 다음의 태그를 사용할 수 있다.

 

@param 변수 설명
이 태그는 현재 메소드의 매개변수들 부분에 엔트리를 추가한다.
설명은 여러 라인에 걸쳐 존재할 수 있고 HTML 태그들을 사용할 수 있다.
하나의 메소드를 위한 모든 @param 태그들은 함께 유지돼야 한다.
오직 메소드들에서만 사용할 수 있다.

 

@return 설명
이 태그는 현재 메소드에 “Return” 세션을 추가한다.
설명은 여러 줄에 걸쳐 존재할 수 있고 HTML 태그들을 사용할 수 있다.

 

@throws 클래스 설명
이 태그는 현재 메소드에 “Throws” 세션에 대한 항목을 추가하고 자동적으로 하이퍼링크를 설정한다.
설명은 여러 라인에 걸쳐 존재할 수 있고 HTML 태그들을 사용할 수 있다. 하나의 메소드를 위한

모든 @throws 태그들은 함께 유지돼야 한다. 오직 메소드들에서만 사용할 수 있다.

 

다음은 메소드 주석의 예이다:

/**

Formats a double into a strong (like <tt>sprintf</tt> in C)

@ param x the number to format

@ return the formatted string

@ throws IllegalArgumentException if bad argument

*/

 

 

 

[ 연속 주석 ]

자바 1.2 에서 문서 오브젝트 연속(serialization)에는 세 가지의 새로운 태그가 있다.
이렇게 기술은 하지만, 아직 전반적으로 지원치는 못한다.

 

@ serial 텍스트
이러한 태그는 기본 연속적 메커니즘을 오버라이드 하지 않는 Serializable 인터페이스를 충족시키는
클래스 내에서 static 하지 않거나 transient 하지않은 모든 필드들에 사용이 된다. 이러한 말은 마치

많은 문제점을 가지는 것으로 보이지만 각 필드가 안전하게 시리얼라이즈 되는가를 다시 생각하게 한다.

모든 사람들에게 이러한 요구가 얼마나 성가신 것인가를 알게 된다면 우리는 분명 이를 없앨 것이다.

선택적인 text 는 필드의 정당한 값들의 표현을 포함한다. 테스트에 사용한 javadoc 의 버전에서

시리얼라이즈 필드에서 @serial 주석을 빠트린다면 경고가 주어질 것이다.

 

@serialField name type text
기본 시리얼라이즈 메커니즘을 오버라이드하는 클래스의 serialPersistnetFields 배열에 모든 필드에 대하여
이 태그를 사용할 수 있다.

 

@serialData text
writerObject 나 writeExternal 메소드로 작성된 추가적 데이터를 설명 할 때 사용하는 태그이다.
이 태그는 데이터를 읽거나 쓰는 메소드를 문서화할 곳에 둔다.

 

 

 

[ 패키지와 개요 주석 ]

클래스와 메소드, 변수 주석은 /** . . . */의 문서 주석에 의하여 구분되어져서 직접적으로 자바 소스 파일에 위치한다. 하지만 패키지 주석을 생성하기 위하여는 패키지 디렉토리에 package.html 파일 이름을 추가하여야 한다. <BODY>. . . </BODY> 태그 사이의 텍스트는 추출된다. 모든 소스 파일에 대하여 개요 주석을

추가하여야 한다. Overview.html 이라 불리는 파일에 위치시키고, 원하는 소스 파일을 포함하는

부모 디렉토리에 위치시킨다. <BODY>. . .</BODY> 태그 사이의 텍스트는 추출된다.

이 주석은 사용자가 네비게이션 바에서 Overview를 선택하면 표현된다.

 

 

 

[ 주석들을 추출하는 방법 ]

여기서, docDirectory 는 HTML 파일이 가기를 원하는 디렉토리의 이름이다. 아래의 단계를 따른다.

 

1. 원하는 문서의 소스 코드를 포함하는 디렉토리로 이동한다.
   com.corejava 와 같은 페키지들을 문서에 넣는다면, 서브디렉토리 com 을 포함하는 디렉토리에 있다.

 

2. 명령을 수행하라.

   1) 단일 패키지 일 경우:  javadoc –d docDirectory nameOfPackage

   2) 다중 패키지의 경우: javadoc –d docDirectory nameOfPackage1 nameOfPackage2 . . .

 

javadoc 프로그램은 다양한 명령 라인 옵션으로 잘 변형 되어 질 수 있다.

예를 들어, -author 나 –version 옵션을 문서에서 @author 나 @version 태그를 포함하기 위하여

이용할 수 있다. javadoc 유틸리티의 온라인 문서(http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html)를 참고하라.

 

예를 들어 HTMLdhldml 형태의 문서를 만들기 위해서 더 많은 사용자정보를 원한다면,

원하는 어떠한 형태의 결과물을 생성하기 위해 doclet 를 사용할 수 있다.

이러한 것은 특수한 요구이므로 doclet 들의 자세한 내용은 온라인상의 문서를 이용하기를 권한다.