728x90
JDK에는 javadoc이라는 도구가 포함되어 있다. javadoc은 소스 파일로 HTML 문서를 만든다. Java API 문서는 표준 자바 라이브러리의 소수 코드로 javadoc을 실행한 결과다. 소스 코드에 구분자 /**로 시작하는 주석을 추가하면 javadoc을 이용하여 전문가 수준의 문서를 손쉽게 만들 수 있다.
1. 문서화 주석
1.1 주석 넣기
▷ javadoc 추출 정보
- javadoc 유틸리티는
패키지,공개 클래스와 인터페이스,공개/보호 변수,공개/보호 생성자와 메서드정보를 추출한다.- 기능 각각에 주석을 달 수 있고, 주석은 설명할 기능 바로 위에
/**로 시작하고*/마쳐 작성할 수 있다.- 문서화 주석(/*_ ... _/)에는 자유 형식 텍스트와 태그들을 적는다.
- 태그는
@author나@param처럼@기호로 시작한다.- 자유 형식 텍스트에는 HTML 태그
<em>,<code>,<strong>,<img>태그를 사용할 수 있다.- 이미지를 넣을 때에는 소스 파일 디렉터리에
doc-files디렉터리를 만들어 넣는다.
1.2 클래스 주석
- 클래스 주석은 반드시 클래스 선언부 바로 앞에 위치해야 한다.
@author태그로 저자를 문서화한다.@version태그로 버전을 문서화한다.
1.3 메서드 주석
- 각 메서드 주석은 해당 메서드 바로 앞에 위치해야 한다.
@param {변수} {설명}태그로 각 파라미터를 문서화한다.@return {설명}태그로 반환 값을 문서화 한다.@throws {예외클래스} {설명}태그로 예외를 문서화한다.
1.4 변수 주석
- 공개 변수(일반적으로
정적 상수를 의미)만 문서화한다.
/**
* 연간 일수(윤년 제외)
*/
public static final int DAYS_PER_YEAR = 365;1.5 일반 주석
- 모든 문서화 주석에
@since태그로 해당 기능을 이용할 수 있는 버전을 적어줄 수 있다.@deprecated태그에는 해당 클래스, 메서드, 변수를 사용하지 말아야 한다는 주석을 추가한다. 설명에는 대체 방법을 제안해야 한다.
@deprecated Use <code>setVisible(true)</code> instead1.6 링크
@see태그와@link태그로 javadoc 문서의 관련 부분이나 외부 문서에 대한 하이퍼링크를 추가할 수 있다.
▷ @see 태그
@see태그는'참고'세션에 하이퍼링크를 추가한다. 클래스와 메서드에 모두 사용할 수 있다.패키지.클래스#특징레이블<a href="...">레이블</a>"텍스트"- 클래스를 메서드나 변수의 이름과 구분할 땐 점이 아니라
#을 사용해야 한다.- 태그 뒤에
"문자가 오면 큰따옴표 안에 있는 텍스트가'참고'섹션에 표시된다.
@see com.test.java.Employee#raiseSalary(double)▷ @link 태그
@link태그는 문서화 주석의 어느 위치에라도 다른 클래스나 메서드의 하이퍼링크를 넣을 수 있다.
{@link 패키지.클래스#특징레이블}1.7 패지지 주석과 개요 주석
▷ 패키지 주석
패키지 주석은 패키지 디렉터리에package-info.java파일을 추가한다.- 이 파일의 첫 부분에는
/**와*/로 구분한 javadoc 주석이 있어야 하고, 그 뒤에는패키지 문이 있어야 한다.- 패키지 문이 작성된 이후로는 코드나 주석을 적지 말아야 한다.
▷ 개요 주석
개요 주석은 모든 소스 파일이 들어 있는 부모 디렉터리에overview.html파일을 추가한다.<body>...</body>태그 사이에 오는 텍스트는 모두 추출된다.- 개요 주석은 사용자가 내비게이션 바에서
개요(overview)를 선택하면 표시된다.
1.8 주석 내보내기
javadoc -d {내보낼 문서 디렉터리} {패키지1} {패키지2} ...728x90
'Java' 카테고리의 다른 글
| [Java] Maven 라이브러리 Dependency 충돌 해결하기 (0) | 2021.11.04 |
|---|---|
| [Java] 메서드 참조(Method Reference) (0) | 2021.05.21 |
| [Java] 와일드 카드가 들어간 IP 검사하기! (0) | 2020.07.13 |
| [Java] StringBuffer / StringBuilder (0) | 2020.06.02 |
| [Java] BufferedReader / BufferedWriter 사용법 (0) | 2020.06.01 |