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);

자바 1.5부터는 패키지 수준 문서화 주석(package-level doc comment)은 package.html대신 package-info.java에 두어야 한다.

javadoc tag를 달자.

주석을 달 때 명심해야 일번적 원칙은, 문서화 주석은 소스 코드로 보나 javadoc으로 변환한 결과물로 보나 읽을 만해야 한다.

참고 : How to Write Doc Comments for the Javadoc Tool