Item 44. 모든 API 요소에 문서화 주석을 달라.
좋은 API 문서를 만들려면 API에 포함된 모든 클래스, 인터페이스, 생성자, 함수, 그리고 필드 선언에 문서화 주석을 달아야한다.
/**
* Returns the element at the specified position in this list.
*
* <p>This method is <i>not</i> guaranteed to run in constant
* time. In some implementations it may run in time proportional
* to the element position.
*
* @param index index of the element to return; must be
* non-negative and less than the size of this list
* @return the element at the specified position in this list
* @throws IndexOutOfBoundsException if the index is out of range
* ({@code index < 0 || index >= size()})
*/
E get(int index);
- 제네릭 자료형이나 함수에 주석을 달 때는 모든 자료형 인자들을 설명해야한다. ```java /**
- An object that maps keys to values (중략) *
- @param
the type of keys maintained by this maps -
@param
the type of mapped values */ public interface Map<K, V> { .... } ``` - enum자료형에 주석을 달 때는 자료형이나 public함수 뿐 아니라, 상수 각각에도 주석을 달아 주어야 한다. ```java /**
-
교향악단에서 쓰이는 악기 종류 */ public enum OrchestraSection{ /** 플루트, 클라리넷, 오보와 같은 목관악기 */ WOODWIND,
/** 프렌치 혼이나 트럼펫 같은 금관 악기 */ BRASS,
/** 팀파니나 심벌즈 같은 타악기 */ PERCUSSION,
/** 바이올린이나 첼로 같은 현악기 */ STRING; } ```
- 어노테이션 자료형에 주석을 달 때는 자료형 뿐 아니라 모든 멤버에도 주석을 달아야 한다. ```java /**
- 지정된 예외를 반드시 발생시켜야 하는 테스트 함수임을 명시.
*/
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ExceptionTest {
/**
- 어노테이션이 붙은 테스트 함수가 테스를 통과하기 위해 반드시 발생시켜야 하는 예외.
- (이 Class 객체가 나타내는 자료형의 하위 자료형이기만 하면 어떤 예외든 상관없다.) */ Class<? extends Throwable> value(); } ```
자바 1.5부터는 패키지 수준 문서화 주석(package-level doc comment)은 package.html
대신 package-info.java
에 두어야 한다.
javadoc tag를 달자.
@param
인자@return
반환값을 설명@throws
어떤 조건(if)에 예외가 발생하는지 설명{@code}
코드 서체로 표기, HTML 마크업 무력화{@literal}
{@code}
와 비슷하나 코드 서체로 표기되지 않음
주석을 달 때 명심해야 일번적 원칙은, 문서화 주석은 소스 코드로 보나 javadoc으로 변환한 결과물로 보나 읽을 만해야 한다.
참고 : How to Write Doc Comments for the Javadoc Tool