JavaDOC 사용하기

Javadoc는 링크된 html 파일의 표준 집합을 생성한다.
Javadoc로 만들어지는 출력물의 정확한 양식은 도클릿(doclet)에 의해 결정되어지며,
표준 javadoc 출력은 유틸리티와 함께 제공되는 표준 도클릿의 결과로 만들어진다.

 

 

 

 

 

[ JavaDoc으로 만들어진 주 문서 ]

- Overview-tree.html : 모든 클래스와 인터페이스들의 트리 표현을 담고 있다.
- Serialized-form.html : 프로그램 코드에서 직렬화 할 수 있는 모든 클래스들의 직렬화된 형식에 대한

                                       정보를 담고 있다.
- Index-all.html : 모든 클래스, 인터페이스와 그들의 멤버들에 대한 색인을 제공한다.
- deprecated-list.html : 모든 권장되지 않는 사항들의 이름들을 리스트한다.
- ClassName.html : 프로그램의 다른 곳에서 사용되는 클래스 혹은 인터페이스의 위치를 리스트한다.
- help-doc.html : 문서를 사용하는 방법에 대한 일반화된 도움 도구들을 담고 있다.

 

 

 

 

[ JavaDOC 사용 방법 ]

/**
 *
 *
 */

 

각 줄 첫부분의 *는 주석이 되지 않으며, *를 생략한다면

그 줄의 첫번째 비 공백문자 앞의 모든 공백 문자들은 폐기된다.
문서 주석의 텍스트는 html이 되므로 태그들을 포함시킬수 있다.
단, <h1>과 같은 제목 태그는 클래스와 패키지의 주석에서만 포함시킬 수 있다.
“<” -> < “>”->> “&”->&를 사용하거나 html파일이나 이미지 파일과 같은 다른 파일들을 삽입할 수도 있다.

* <img src=”javae/java.gif”>

 

 

 

 

 

[ 특수 문서화 태그 ]

@author : 제작자 엔트리를 생성하는데 사용
@version : 코드의 버전 정보를 기술하는데 사용
@see : 다른 클래스, 메소드, 필드와 같이 다른 이름을 가진 프로그램의 엔터티에 대한 링크를 제공한다.

            외부의 페이지를 링크할 수도 있다.

@param : 메소드의 파라미터를 설명하는데 사용
@return : 메소드가 void가 아닌 다른 값을 리턴할 때 메소드의 리턴값을 설명한다.
@exception : 메소드가 발생시킬 수 있는 예외를 정의한다.
@throws : @exception과 동일
@deprecated : 메소드가 권장되지 않음을 지정한다.
@serialData : writeObject(), readObject(), writeExternal(), readExternal() 메소드를

                       읽거나 쓸 수 있는 데이터 아이템을 설명하는데 사용.

@serialField : ObjectStreamField 객체를 설명하는데 사용
@serial : 기본적으로 직렬화할 수 있는 클래스의 데이터 멤버를 설명하는데 사용
@since : 어떠한 특성이 코드에 소개된 시점을 가리키는데 사용한다.
{@link #entity label} : 소스코드의 또 다른 엔터티의 문서에 대한 내부링크를 추가하는 효과를 나타낸다.
                                     * 태그 이름의 대소문자를 구별해야 한다는 것을 유의해야 한다.

 

 

<사용의 예>
* @author 4offline
* @version 1.0.1 November 3 2001
* @since version 1.0.1
* @see <a href=”doc-files/jdbc1.html”> jdbc1 </a>
* @throws exceptiontype description
* @param parameterName description
* @return description
* @serial description
* @serialField fieldname fieldType description

 

 

 

[ Javadoc의 실행 ]

 

    

   javadoc [options] [packages] [sourcefiles] [@files]

 

 

 

<option>

- author : @author 태그의 출력이 생성된다.
- version : @version 태그의 출력이 생성된다.
- public : 문서출력을 public 클래스와 멤버들로 제한한다.

               기본적으로는 public 클래스와 public/protected 멤버들로 제한.

- protected : public 클래스와 protected/public 클래스 멤버로 제한
- private : 모든 클래스와 멤버들이 문서화된다.
- package : 문서 출력을 패키지, protected/public 클래스와 멤버로 제한
- use : 각 클래스와 인터페이스 문서의 일부로서 용법클래스 생성. 특정 클래스 또는

           인터페이스가 참조되는 곳에 대한 리스트

- overwiew pathfilename : 개표 페이지에 보이게 될 텍스트를 포함하는 파일의 경로와 이름을 지정한다.
- ddirectoryName : 지정한 디렉토리에 html파일들을 저장한다.
- sourcepath pathList : javadoc이 처리할 패키지들을 찾기 위한 경로를 지정
- classpath pathList : javadoc이 문서화 주석에서 참조할 클래스들을 찾기 위한 경로
- extdirs dirList : 자바 확장 메커니즘을 사용하는 클래스들을 포함하는 디렉토리들의 리스트를 지정
- bootclasspath pathlist : 자바 플랫폼 클래스들을 찾기 위한 경로를 지정
- serialwarn : @serial 태그를 빠트렸을 때 경고 메시지 표시
- verbose : javadoc이 실행되는 동안 더 포괄적인 메시지를 만들도록 한다.

 

 

 

 

[ Eclipse 에서의 사용법 ]

 

1. Project → Generate JavaDoc

   

 

 

2. JavaDoc에 포함되길 원하는 자바 클래스 소스를 선택

   

 

 

3. 문서의 제목(브라우저 title바에 표시될 내용)을 설정하고 아래 리스트에서 링크가 걸릴 jar를 선택한다.

    이미 javadoc을 지정한 항목은 옆에 주소가 나오지만 안나오는 것을 선택했다면 Browse 버튼을 누르고

    지정해주면 된다.

   

    

   

 

 

 

4. 마지막으로 한글을 사용했다면 해당 인코딩을 지정한다.

   -encoding UTF-8 이나 -encodeing EUC-KR 과 같은 식이다.