- API 문서화 유틸리티
- 소스코드 파일에서 문서화 주석(자바독 주석)이라는특수한 형태로 기술된 설명을 추려 API 문서로 변환해준다.
$ javadoc -d docs {file_name}
$ javadoc -d docs *.java -encoding UTF-8 -charset UTF-8 -docencoding UTF-8
- 주석을달지 않으면 그저 공개된 API 요소들의 '선언'만을 나열한다.
- 공개 클래스는 기본 생성자에 주석을 달 수 있는 방법이 없으니 절대 기본 생성자를 사용해서는 안된다.
- how가 아닌 what을 기술할 것. (상속용으로 설계된 API가 아닌 이상)
- 메서드를 성공적으로 호출하기 위한 전제조건을 나열할 것
- 메서드가 성공적으로 수행된 후에 만족해야 하는 사후조건을 나열할 것
- 부작용(사후조건으로 명확하게 나타나지는 않지만 시스템의 상태에 어떠한 변화를 가져오는 것)도 문서화할 것 (ex. 백그라운드 스레드를 시작하는 메서드)
- 매개변수가 뜻하는 명사구
- 모든 매개변수에 설명을 달아야 한다.
- 반환 값을 설명하는 명사구
- 반환 타입이 void가 아니라면 달아야 한다.
- if로 시작해 해당 예외를 던지는 조건을 설명하는 절
- 주석 내에 HTML 요소나 다른 자바독 태그를 무시한다.
- 주석에 여러 줄로 된 코드 예시를 넣으려면
{@code}를<pre>태그로 감싸준다.<pre>{@code ...코드... }</pre>
- 주석 내에 HTML 요소나 다른 자바독 태그를 무시한다.
{@code}와 비슷하지만 코드 폰트로 렌더링하지 않는다.
- 해당 메서드와 하위 클래스 사이의 계약을 설명한다.
- 하위 클래스들이 그 메서드를 상속하거나 super 키워드를 이용해 호출할 때 그 메서드가 어떻게 동작하는지 명확히 인지할 수 있도록 도와준다.
- 상위 타입의 문서화 주석 일부를 상속할 수 있다.
package chapter8.item56;
/**
* @author jiae
* 게임 캐릭터의 정보를 가지고 있는 클래스
*/
public class GameCharactor {
private int level;
private String name;
private String weapon;
private Job job;
/**
* 게임 캐릭터를 생성합니다.
* <p>기본 무기는 목검, 기본 직업은 Beginner입니다.
* @param name 캐릭터의 이름; 길이는 3자 이상 10자 이하이어야 합니다.
* @throws IllegalArgumentException 캐릭터의 name 길이가 정해진 범위를 벗어나면, 즉 ({@code name < 3 || name > 10}) 이면 발생합니다.
*/
public GameCharactor(String name) {
this.level = 1;
if (name.length() < 3 || name.length() > 10) throw new IllegalArgumentException("캐릭터의 이름은 3자 이상 10자 이하입니다.");
this.name = name;
this.weapon = "목검";
this.job = Job.Beginner;
}
/**
* 캐릭터의 레벨을 반환합니다.
* @return 캐릭터의 레벨
*/
public int getLevel(){
return this.level;
}
/**
* 캐릭터의 직업을 변경합니다.
* @param job 캐릭터의 변경할 직업
* @throws IllegalArgumentException 캐릭터의 레벨이 10이 넘지 않았다면 발생합니다.
*/
public void setJob(Job job){
if (this.level < 10) throw new IllegalArgumentException("캐릭터의 레벨이 10을 넘지 않습니다.");
this.job = job;
}
/**
* 캐릭터의 무기를 변경해주는 메서드입니다.
* @param weapon 캐릭터가 착용할 무기
* @param weaponLevel 무기의 레벨
* @throws IllegalArgumentException 캐릭터의 레벨보다 무기의 레벨이 높으면 발생합니다.
*/
public void setWeapon(String weapon, int weaponLevel){
if (weaponLevel > this.level) throw new IllegalArgumentException("캐릭터의 레벨보다 무기의 레벨이 높습니다.");
this.weapon = weapon;
}
/**
* 캐릭터의 레벨을 올려주는 메서드입니다.
*/
public void levelUp(){
this.level++;
}
/**
* 캐릭터의 status값을 보여주는 메서드입니다.
* @return 직업, 레벨, 이름, 무기를 반환합니다.
*/
public String getCharactorStatus() {
return "GameCharactor [job=" + job + ", level=" + level + ", name=" + name + ", weapon=" + weapon + "]";
}
/**
* 캐릭터의 직업을 나타냅니다.
*/
public enum Job{
/** 초보자 */
Beginner,
/** 전사 */
Warrior,
/** 마법사 */
Wizard,
/** 궁수 */
Archer,
/** 도적 */
Thief
}
}
-
- 클래스 혹은 정적 메서드가 스레드 안전하든 그렇지 않든,
쓰레드 안전 수준을 반드시 API 설명에 포함해야 한다.
- 클래스 혹은 정적 메서드가 스레드 안전하든 그렇지 않든,
-
- 직렬화할 수 있는 클래스라면 직렬화 형태도 API 설명에 기술해야 한다.
- 문서화 주석은 aPI를 문서화하는 가장 훌륭하고 효과적인 방법이다.
- 공개 API라면 빠짐없이 설명을 달아야 한다.
- 표준 규약을 일관되게 지키자.
- 문서화 주석에 임의의 HTML 태그를 사용할 수 있음을 기억하라. 단, HTML 메타문자는 특별하게 취급해야 한다.
- Effective Java 3/E