Item 56 : 공개된 API 요소에는 항상 문서화 주석을 작성하라

• 이번 챕터는 API 문서 작성 요령이다.
• 우리의 API를 올바로 문서화하려면 공개된 모든 클래스, 인터페이스, 메소드, 필드 선언에 문서화 주석을 달아야 한다.
• 메소드용 문서화 주석에는 해당 메소드와 클라이언트 사이의 규약을 명료하게 기술해야 한다.
  • 메소드가 무엇을 하는지(how가 아닌 what)
  • 메소드를 호출하기 위한 전제조건
  • 수행된 후 만족해야하는 사후조건
  • 부작용

• 문서화의 첫 설명은 요약설명
• 첫번째 . 기호가 나타나기 전까지가 첫번째 문장

 

 

문서화 태그

태그	설명
@author 이름	클래스나 인터페이스의 제작자 표시
@version 테스트	클래스나 인터페이스에서의 버전 정보
@param 매개변수 - 이름 설명	매개 변수에 대한 설명
@return 설명	메소드가 void를 리턴하거나 생성자가 아닌 경우를 제외하고 모두 사용해야 함
@exception or @throws	메소드가 발생시킬 수 있는 예외를 기술
@deprecated	다음 버전에서 폐기된 메소드를 알림
@serial	기본적으로 직렬화 할 수 있는 클래스의 멤버를 설명
@see	- 어떤 클래스, 인터페이스, 메소드, 생성자 혹은 URL에 대한 전후 참조 표시 - 분리된 줄에 링크가 생김
@since	Tag를 가진 객체가 언제 추가되었는지 명시
{@link #entity label}	메소드나 필드의 상호 참조에 대한 링크를 표시 문서 텍스트 안에 링크가 생김
{@doc-root}	문서에 대한 루트디렉토리에 대한 상대경로 지정

 

사용 예시

/**
* 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
* @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);

• 문서화 주석에 HTML태그도 사용했다.

 

 

제네릭 타입

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

 /* 
 * An object that maps keys to values.  A map cannot contain duplicate keys;
 * each key can map to at most one value.
 *
 * @param <K> the type of keys maintained by this map
 * @param <V> the type of mapped values
 */
public interface Map<K, V> {

 

 

열거타입

• 상수들에도 주석을 달아야함

/**
* An instrument section of a symphony orchestra
*/
public enum OrchestraSection {
    /** WoodWinds, such as flute, clarinet and oboe */
    WOODWIND,
    /** Brass instruments, such as french horn and trumper */
    BRASS,
    /** Percussion instruments, such as timpani, cymbals */
    PERCUSSION,
    /** Stringed instruments, such as violin and cello */
    STRING
}

 

 

어노테이션

• 어노테이션 타입을 문서화 할 때는 멤버들에도 모두 주석을 달아야함

/**
 * Indicates that the annotated method is a test method that 
 * must throw the designated exception to pass
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ExceptionTest {
    /**
     *  The exception that the annotated test method must throw
     *  in order to pass. (The test is permitted to throw any subtype
     *  of the type described by this class object.)
     */
    Class<? extends Throwable> value();
}

 

 

스레드 안전 수준을 반드시 API설명에 포함해야 한다.

• 추가적으로 직렬화 할 수 있는 클래스라면 직렬화 형태로 API 설명에 기술해야 함

 

 

정리

• 문서화 주석은 API를 문서화하는 가장 훌륭하고 효과적인 방법
• 공개 API라며 빠짐없이 설명 달아야함
• 표준 규약을 일관되게 지키자
• 문서화 주석에 HTML 태그 사용 가능
  • 특별하게 취급해야 한다.
• https://docs.oracle.com/javase/8/docs/api/를 참고할것