API 문서화

문서화 주석

API를 올바르게 문서화하려면 공개도니 모든 클래스, 인터페이스, 메서드, 필드 선언에 문서화 주석을 달아야한다.

Java에서는 자바독(javadoc)이라는 유틸리티가 이 귀찮은 작업을 도와준다.

  • java 5의 @literal, @code
  • java 8의 @implSpec
  • java 9의 @index

각 버전별 주요 자바독 태그로 자세한 설명은 정리를 참고하자.

정리

  • 상속용으로 설계된 클래스의 메서드가 아니라면, 무엇(what)을 하는지 기술해야한다.
  • 해당 메서드를 호출하기 위한 전제조건을 모두 나열해야한다.
    • 전제 조건은 @throws 태그로 비검사 예외를 선언하여 암시적으로 기술
    • @param 태그로 해당 조건에 영향받는 매개변수에 기술
  • 메서드가 성공적으로 수행된 후 만족해야하는 사후 조건도 모두 나열해야한다.
  • 시스템의 상태에 변화를 가져오는 부작용도 기술해야한다.
    • 예를 들어 백그라운드 스레드를 시작시키는 메서드일 경우 이를 기술해야 한다.
  • @param 태그 : 모든 매개변수에 추가한다.
  • @return 태그 : 반환 타입이 void가 아니라면 필수이다.
    • 메서드 설명과 동일한 경우 생략 가능하다.
  • @throws 태그 : 발생할 가능성이 있는 모든 예외에 추가
  • 문서화 주석에 HTML 태그를 사용할 수 있다.
    • 자바독 유틸리티는 문서화 주석을 HTML로 변환하므로, HTML 요소들이 최종 문서에 반영된다.
  • {@code} 태그
    • 태그로 감싼 내용을 코드용 폰트로 렌더링한다.
    • 태그로 감싼 내용에 포함된 HTML 요소나 다른 자바독 태그 무시한다.
    • 여러 줄로된 코드 예시는 <pre>{@code}</pre> 형태로 사용
  • 영문 문서화 주석에서 "this"는 호출된 메서드에 사용된 객체를 가리킨다.
  • @implSpec : 해당 메서드와 하위 클래스 사이의 관계를 설명한다.
    • 하위 클래스들이 해당 메서드를 상속하거나 super 키워드 이용해 호출시 어떻게 동작하는지 명확히 설명한다.
    • Java 11 까지 -tag "implSpec:a:Implementation Requirements:" 스위치를 켜주지 않으면 @implSpec 태그를 무시한다.
  • {@literal} 태그 : HTML 마크업이나 자바독 태그 무시한다.
    • 이는 >, <, & 등 메타문자를 포함한다.
  • 각 문서화 주석의 첫문장은 해당 요소의 요약 설명을 기술한다.
    • 한 클래스 내에 요약 설명이 똑같은 멤버는 둘 이상이면 안된다.
  • 요약 설명(summary description)
    • java10 이전에는 요약설명이 끝난다고 판단되는 기준은 '.' 마침표로 마침표 사용시 주의한다. 마침표를 포함한 텍스트를 {@literal}로 감싸주는 것이 좋다.
    • java10 이후는 {@summary} 요약 설명 전용 태그를 사용한다.
    • 메서드와 생성자의 요약 설명은 해당 메서드와 생성자의 동작을 설명하는 (주어 없는) 동사구
    • 클래스, 인터페이스, 필드의 요약설명은 대상을 설명하는 명사절
  • {@index} 태그는 API 문서에 검색(색인) 기능 추가(java9 이후)
  • 제네릭 타입이나 제네릭 메서드 문서화시 모든 타입 매개변수에 주석을 달아야한다.
  • 열거 타입 문서화시 상수들에도 주석을 달아야한다.
  • 어노테이션 타입 문서화시 멤버들 모두 주석을 달아야한다.
  • 패키지 모듈 별 문서화
    • 패키지 문서화는 pakage-info.java에 작성한다.
    • 모듈 문서화는 module-info.java (java9 이상 지원)
  • 클래스/정적 메서드에 스레드 안전 수준을 반디시 명시해야한다.
  • 직렬화 클래스라면 직렬화 형태도 기술해야한다.
  • 자바독은 메서드 주석을 '상속' 가능하다.
    • 문서화 주석이 없는 API요소 발견시 가장 가까운 문서화 주석을 찾는다.
    • 인터페이스가 상위 클래스보다 우선순위가 높다.
  • {@inheritDoc} : 상위 타입의 문서화 주석 일부를 상속할 수 있다.
  • 주석만으로 설명하지 못하는 경우 관련 클래스나 패키지에서 별도 설명 링크를 제공하자.
  • java 7 -Xdoclint 스위치를 켜주면, 문서를 올바르게 작성했는지 검사해주며, java8부터는 default 값이다.
  • java9,10에서는 html5 스위치를 켜면, HTML5로 만들고 기본은 HTML4.

참고자료

  • 이펙티브자바 3판