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

자바독(Javadoc)

• 소스코드 파일에서 문서화 주석이라는 특수한 형태로 기술된 설명을 추려 API문서로 변환한다.
• API를 올바르게 문서화하려면 공개된 모든 클래스, 인터페이스, 메서드 , 필드 선언에 문서화 주석을 달아야 한다.
• 문서가 잘 갖춰지지 않은 API는 쓰기 헷갈려서 오류의 원인이 되기 쉽다.
• 공개 클래스는 절대 기본 생성자를 사용하면 안 된다(기본 생성자에는 주석 X)

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

• How가 아닌 What을 기술할 것
• 클라이언트가 해당 메서드를 호출하기 위한 전제조건을 모두 나열할 것
• 성공적으로 수행된 후에 만족해야 하는 사후 조건도 모두 나열할 것
• 전제조건은 @throws 태그로 비검사 예외를 선언하여 암시적으로 기술할 것
• @param 태그를 이용해 조건에 영향받는 매개변수에 기술할 것
• 부작용도 문서화할 것 

Tag 정리

• 모든 매개변수에 @param 태그 사용할 것
• 반환 타입이 void가 아니면 @return을 사용할 것
  • param, return 태그의 설명은 해당 매개변수나 리턴 값을 설명하는 명사구를 사용
• 모든 예외에 @throws 태그를 사용할 것
• @code
  • 태그로 감싼 내용을 코드용 폰트로 렌더링하고 그 내용에 포함된 HTML 요소나 다른 자바 독 태그를 무시한다.
• 클래스를 상속용으로 설계할 때 @implSpec을 사용할 것(자기 사용 패턴)
  • 일반적인 문서화 주석은 해당 메서드와 클라이언트 사이의 계약을 설명하지만, @implSpec 주석은 해당 메서드와 하위 클래스 사이의 계약을 설명함
• @literal 
  • 태그를 감싸면 API 설명에 <,>,& 등의 HTML 메타 문서를 포함할 수 있음
• @index 태그(자바 9 추가) 
  • API에서 중요한 용어를 추가로 색인화할 수 있음.
• @inheritDoc 태그
  • 상위 타임의 문서화 주석 일부를 상속할 수 있음. (클래스는 자신이 구현한 인터페이스의 문서화 주석을 재사용할 수 수 있음)

  

문서화 주석에서 제네릭, 열거 타입, 애너테이션은 주의해야 한다.

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

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

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

 

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

모듈 관련 설명하는 문서화 주석은 module-info.java 파일에 작성한다. 

 

API 문서화에 자주 누락되는 설명 2가지

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

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

문서화 주석이 없는 API 요소를 발견하면 자바 독이 가장 가까운 문서화 주석을 찾아준다.

 

---

핵심정리

• 문서화 주석은 API를 문서화하는 가장 효과적인 방법이다.
• 공개 API라면 빠짐없이 설명을 달아야 한다.
• 표준 규약을 일관되게 지키면서 달자.
• 문서화 주석에 임의의 HTML 태그를 사용할 수 있다. 단, HTML 메타 문자는 특별하게 취급해야 한다.

---

참고자료

www.kyobobook.co.kr/product/detailViewKor.laf?ejkGb=KOR&mallGb=KOR&barcode=9788966262281&orderClick=LEa&Kc=

이펙티브 자바 3/E - 교보문고