이번 item에서는 javaDoc 작성 규칙을 다룬다.

소스코드 파일에서 문서화 주석(doc comment)이라는 특수한 형태로 기술된 설명을 추려 API 문서로 변환해주는 유틸리티

• 문서화 주석 작성법(How to Write Doc Comments)
• @inheritDoc 관련 오라클 공식 문서

문서화 주석 작성법은 java 4 이후로 15년째 갱신되지 않고 있다. java 5, 8, 9에 갱신된 @literal, @code, @implSpec 은 위 웹페이지에 설명이 없으므로 이번 장에서 설명할 것이다.

• API의 공개된 모든 클래스, 인터페이스, 메서드, 필드 선언에 문서화 주석을 달아야 한다.

기본 생성자에는 주석을 달 수 없으니, 공개 클래스는 절대 기본 생성자를 사용하지 않는다. 유지보수까지 고려한다면 공개되지 않는 클래스,인터페이스,생성자,메서드,필드에도 간단한 문서화 주석을 다는 것이 좋다.

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

1.상속용으로 설계된 클래스가 아니라면 how가 아닌 what을 기술한다.

2.메서드 호출을 위한 전제조건(precondition)을 모두 나열한다. @throws 태그

3.메서드가 성공적으로 수행된 후 만족해야 하는 사후조건(postcondition)도 모두 나열한다.

4.부작용도 문서화한다.

부작용이란? → 사후조건으로 명확히 나타나지는 않지만 시스템 상태에 어떠한 변화를 가져오는 것. 예를 들면, 백그라운드 스레드를 시작시키는 메서드라면 문서에 밝혀야 한다.

5.모든 매개변수에 @param 태그를, (void가 아니라면)반환타입에 @return 태그를 단다.

파라미터, 리턴, 클래스, 인터페이스, 필드는 명사절로 설명을 작성하고, 메서드는 동사구로 설명을 작성한다. @param, @return, @throws 설명에는 마침표를 붙이지 않는다.

6. 자바독은 문서화 주석을 html로 변환하므로 html요소를 사용 가능하다.

7.@code : 코드용 폰트로 변환. (html요소나 자바독 태그를 무시)

8.<pre></pre> : @code 안의 줄바꿈이 그대로 유지됨

9.this : 인스턴스 메서드의 this는 호출된 메서드가 자리한 객체를 가리킨다.

위의 모든 규약이 들어간 예시

/**
    * 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.</p>
    *
    * @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
    *         (<tt>index &lt; 0 || index &gt;= size()</tt>)
    */
   E get(int index);

일반적인 문서화 주석은 해당 메서드 - 클라이언트 사이의 계약을 설명한다.

하지만 이 주석은 해당 메서드 - 하위 클래스 사이의 계약을 설명하여, 하위 클래스들이 그 메서드를 상속하거나 super 키워드를 이용해 호출할 때 그 메서드가 어떻게 동작하는지를 명확히 인지하고 사용하도록 해줘야 한다.

(java 11 기준)최신 자바버전인 아직도 자바독 명령줄에 -tag "implSpec:a:Implementation Requirements:" 스위치를 켜줘야 이 태그를 인식한다.

/**
  * Returns true if this collection is empty.
  *
  * @implSpec 
  * This implementation returns {@code this.size() == 0}
  *
  * @return true if this collection is empty
  */
 public boolean isEmpty() {...}

<, >, & 등의 HTML 마크업이나 자바독 태그를 무시하게 해준다.

각 문서화 주석의 첫 번째 문장은 해당 요소의 요약 설명(summary description)으로 간주된다.

메서드와 생성자의 요약 설명은 동사구여야 한다.

요약 설명이 끝나는 기준은 {<마침표><공백><다음 문장 시작>} 패턴의 <마침표> 까지다.

공백의 기준은 space, tab, new line이며 다음 문장 시작의 기준은 '소문자가 아닌' 문자다.

안 좋은 예를 들어보자

/**
 * A suspect, such as Colonel Mustart or Mrs. Peacock. 
 */
public class Suspect{ ... }

위 예에서 요약 설명은 A suspect, such as Colonel Mustart or Mrs. 까지이다. 원치 않는 상황을 피하고 싶다면, 의도치 않은 마침표를 포함한 텍스트를 {@literal}로 감싸주자.

/**
 * A suspect, such as Colonel Mustart or {@literal Mrs. Peacock}. 
 */
public class Suspect{ ... }

자바 9부터는 자바독이 생성한 html문서에 색인 기능이 추가되었다.

API 문서 오른쪽 위 검색창에서 기본적으로 클래스, 메서드, 필드 등을 검색할 수 있으며,

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

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

상수들에도 주석을 달자. 열거 타입 자체와 그 열거타입의 public 메서드까지 주석을 단다.

멤버들에도 모두 주석을 단다. 애너테이션 타입 자체도 단다.

애너테이션 타입의 요약 설명은 프로그램 요소에 이 애너테이션을 다는 것이 어떤 의미인지를 설명하는 동사구로 작성한다.

package-info.java 파일에 작성한다.

이 파일은 패키지 선언을 반드시 포함해야 하며, 패키지 선언 관련 애너테이션을 추가로 포함할 수도 있다.

모듈 관련 설명을 module-info.java에 작성한다.

클래스 or 정적 메서드가 스레드 안전하든 그렇지 않든, 스레드 안전 수준을 반드시 API 설명에 포함해야 한다.

직렬화할 수 있는 클래스라면 직렬화 형태에 관해서도 적어야 한다.

문서화 주석이 없는 API 요소를 발견하면 자바독은 가장 가까운 문서화 주석을 찾아준다. 상위 '클래스'보다 그 클래스가 구현한 '인터페이스'를 먼저 찾는다.

이 기능을 활용하면 거의 똑같은 문서화 주석 여러 개를 유지보수하는 부담을 줄일 수 있지만, 사용하기 까다롭고 제약이 있다. (참고 : 오라클 공식 문서 http://bit.ly/2vqmCzj)

여러 클래스가 상호작용하는 복잡한 API라면 문서화 주석 외에도 전체 아키텍처를 설명하는 별도의 설명이 필요할 때가 있다. 이런 설명 문서가 있다면 관련 클래스나 패키지의 문서화 주석에서 그 문서의 링크를 제공하자.

자바독 문서를 올바르게 작성했는지 확인하는 기능

• java 7 : 명령줄에서 -Xdoclint 스위치를 켜준다.
• java 8 : 위 기능이 기본으로 작동한다.
• IDE 플러그인 checkStyle
• HTML 유효성 검사기를 사용
• W3C 마크업 검사 서비스(W3C-validator)

그러나, 자바독이 잘 쓰였는지 확인하는 확실한 방법은 결국 자바독 유틸리티가 생성한 웹페이지를 읽어보는 길뿐이다.