[이펙티브 자바] 56. 공개된 API 요소에는 항상 문서화 주석을 작성하라

문서화 주석을 작성하는 규칙은 공식 언어 명세에 속하진 않지만 자바 프로그래머라면 응당 알아야 하는 업계 표준 API라 할 수 있다.

여러분의 API를 올바로 문서화하려면 공개된 모든 클래스, 인터페이스, 메서드, 필드 선언에 문서화 주석을 달아야 한다.

메서드용 문서화 주석에는 해당 메서드와 클라이언트 사이의 규약을 명료하게 기술해야 한다.

@throw태그로 비검사 예외를 선언, @param태그를 이용해 그 조건에 영향받는 매개변수에 기술

전제조건과 사후조건뿐만 아니라 부작용도 문서화해야 한다. ex) 백그라운드 스레드를 시작시키는 메서드

메서드의 계약을 완벽히 기술하려면 모든 매개변수에 @param 태그를, 반환 타입이 void가 아니라면 @return 태그를, 발생할 가능성이 있는 (검사든 비검사든) 모든 예외에 @throws 태그를 달아야 한다.

@throws 절에 사용한 {@code} 태그도 살펴보자.

효과 두 가지

1. 태그로 감싼 내용을 코드용 폰트로 렌더링한다.
2. 태그로 감싼 내용에 포함된 HTML 요소나 다른 자바독 태그를 무시한다.

/**
      * 이 컬렉션이 비었다면 true를 반환한다.
      *
      * @implSpec 이 구현은 {@code this.size() == 0}의 결과를 반환한다.
      *
      * @return 이 컬렉션이 비었다면 true, 그렇지 않으면 false
      */
     public boolean isEmpty() {
         return false;
     }

자바 11까지도 자바독 명령줄에서 -tag “implSpec:a:ImplSpec:a:Implementation Requirements:” 스위치를 켜주지 않으면 @implSpec 태그를 무시해버린다.

한 클래스(혹은 인터페이스) 안에서 요약 설명이 똑같은 멤버(혹은 생성자)가 둘 이상이면 안 된다.

// 문서화 주석에 HTML이나 자바독 메타문자를 포함시키기 위해 @literal 태그 사용 (336쪽)
/**
 * A geometric series converges if {@literal|r| < 1}.
 */
public void fragment() {
}
// 한글 버전 (336쪽)
// /**
//  * {@literal |r| < 1}이면 기하 수열이 수렴한다.
//  */
// public void fragment() {
// }

// 문서화 주석 첫 '문장'에 마침표가 있을 때 요약 설명 처리 (337쪽)
/**
 * A suspect, such as Colonel Mustard or {@literalMrs. Peacock}.
 */
public enum Suspect {
    MISS_SCARLETT, PROFESSOR_PLUM, MRS_PEACOCK, MR_GREEN, COLONEL_MUSTARD, MRS_WHITE
}
// 한글 버전 (337쪽)
// /**
//  * 머스타드 대령이나 {@literal Mrs. 피콕} 같은 용의자.
//  */
// public enum Suspect {
//     MISS_SCARLETT, PROFESSOR_PLUM, MRS_PEACOCK, MR_GREEN, COLONEL_MUSTARD, MRS_WHITE
// }

메서드와 생성자의 요약 설명은 해당 메서드와 생성자의 동작을 설명하는 (주어가 없는) 동사구여야 한다.

자바 10부터는 {@summary}라는 요약 설명 전용 태그 추가
/**
* {@summary A suspect, such a Colonel Mustard or Mrs. Peacock}
*/
public enum Suspect{...}

자바 9부터는 자바독이 생성한 HTML 문서에 검색(색인)기능이 추가되어 광대한 API 문서들을 누비는 일이 한결 수월해졌다.

{@index} 태그를 사용해 여러분의 A{I에서 중요한 용어를 추가로 색인화할 수 있다.

* This method complies with the {@index IEEE 754} standard.

제네릭 타입이나 제네릭 메서드를 문서화할 때는 모든 타입 매개변수에 주석을 달아야 한다.

열거 타입을 문서화할 때는 상수들에도 주석을 달아야 한다.

p339

애너테이션 타입을 문서화할 때는 멤버들에도 모두 주석을 달아야 한다.

패키지를 설명하는 문서화 주석은 package-info.java 파일에 작성한다.

API 문서화에서 자주 누락되는 설명이 두 가지 있으니, 바로 스레드 안전성과 직렬화 가능성이다. 클래스 혹은 정적 메서드가 스레드 안전하든 그렇지 않든, 스레드 안전 수준을 반드시 API 설명에 포함해야 한다. 직렬화 형태도

자바독은 메서드 주석을 ‘상속’시킬 수 있다.

정말 잘 쓰인 문서인지를 확인하는 유일한 방법은 자바독 유틸리티가 생성한 웹페이지를 읽어보는 길뿐이다.