공개된 API 요소에는 항상 문서화 주석을 작성하라
API를 쓸모 있게 하려면 잘 작성된 문서도 곁들여야 한다.
자바에서는 자바독이라는 유틸리티가 이 작업을 도와준다.
자바독은 소스코드 파일에서 문서화 주석이라는 특수한 형태로 기술된 설명을 추려 API 문서로 변환해 준다.
문서화 주석을 작성하는 규칙은 공식 언어 명세에 속하지는 않지만, 자바 프로그래머라면 응당 알아야 하는 표준 API라 할 수 있다.
API를 올바로 문서화하려면 공개된 모든 클래스, 인터페이스, 메서드, 필드 선언에 문서화 주석을 달아야 한다.
직렬화할 수 있는 클래스라면 직렬화 형태에 관해서도 적어야 한다.
문서화 주석이 없다면 자바독도 그저 공개 API 요소들의 '선언'만 나열해 주는 게 전부다.
문서가 잘 갖춰지지 않은 API는 쓰기 헷갈려서 오류의 원인이 되기 쉽다.
기본 생성자에는 문서화 주석을 달 방법이 없으니 공개 클래스는 절대 기본 생성자를 사용하면 안 된다.
한편, 유지보수까지 고려한다면 대다수의 공개되지 않은 클래스, 인터페이스, 생성자, 메서드 필드에도 문서화 주석을 달아야 할 것이다.
메서드용 문서화 주석에는 해당 메서드와 클라이언트 사이의 규약을 명료하게 기술해야 한다.
how가 아니라 what을 기술해야 한다.
문서화 주석에는 클라이언트가 해당 메서드를 호출하기 위한 전제조건을 모두 나열해야 한다.
또한 메서드가 성공적으로 수행된 후에 만족해야 하는 사후조건도 모두 나열해야 한다.
일반적으로 전제조건은 @throws 태그로 비검사 예외를 선언하여 암시적으로 기술한다.
비검사 예외 하나가 전제조건 하나와 연결되는 것이다.
또한, @param 태그를 이용해 그 조건에 영향받는 매개변수에 기술할 수도 있다.
전제조건과 사후조건뿐만 아니라 부작용도 문서화해야 한다.
부작용이란 사후조건으로 명확히 나타나지는 않지만, 시스템의 상태에 어떤 변화를 가져오는 것을 뜻한다.
메서드 계약을 완벽히 기술하려면 모든 매개변수 @param 태그를, 반환 타입이 void가 아니라면 @return 태그를, 발생할 가능성이 있는 모든 예외를 @throws 태그를 달아야 한다.
관례상 @param 태그와 @return 태그의 설명은 해당 매개변수가 뜻하는 값이나 반환 값을 설명하는 명사구를 쓴다.
드물게는 명사구 대신 산술 표현식을 쓰기도 한다.
문서화 주석에 HTML를 사용할 수 있다.
자바독 유틸리티는 문서화 주석을 HTML로 변환하므로 문서화 주석 안의 HTML 요소들이 최종 HTML 문서에 반영된다.
{ @code ... 코드 }는 우선 태그로 감싼 내용을 코드용 폰트로 렌더링한다.
그리고 태그로 감싼 내용에 포함된 HTML 요소나 다른 자바독 태그를 무시한다.
클래스를 상속용으로 설계할 때는 자기사용 패턴에 대해서도 문서에 남겨 다른 프로그래머에게 그 메서드를 올바로 재정의하는 방법을 알려줘야 한다.
자기사용 패턴은 자바 8에 추가된 @implSpec 태그로 문서화한다.
각 문서화 주석의 첫 번째 문장은 해당 요소의 요약 설명으로 간주한다.
이때 요약 설명은 반드시 대상의 기능을 고유하게 기술해야 한다.
즉, 한 클래스 안에 요약 설명이 동일한 멤버가 둘 이사 있으면 안 된다.
다중정의된 메서드들의 설명은 같은 문장으로 시작하는 것이 자연스럽겠지만 문서화 주석에서는 허용되지 않는다.
그리고 "요약 설명이란 문서화 주석의 첫 문장이다."라고 말하면 살짝 오해의 소지가 있다.
주석 작성 규약에 따르면 요약 설명은 완전한 문장이 되는 경우가 드물기 때문이다.
메서드와 생성자의 요약 설명은 해당 메서드와 생성자의 동작을 설명하는 동사구이어야 한다.
한편 클래스, 인터페이스, 필드의 요약 설명은 대상을 설명하는 명사절이어야 한다.
자바 9부터는 자바독이 생성한 HTML 문서에 검색 기능이 추가되었는데 이때 중요한 단어의 경우 {@index} 태그를 통해 추가로 색인화 할 수 있다.
문서화 주석에서 제네릭, 열거 타입, 애너테이션은 특별히 주의해야 한다.
제네릭 타입이나 제네릭 메서드를 문서화할 때는 모든 타입 매개변수에 주석을 달아야 한다.
열거 타입을 문서화할 때는 상수들에도 주석을 달아야 한다.
애너테이션 타입을 문서화 할때는 멤버들에도 모두 주석을 달아야 한다.
패키지를 설명하는 문서화 주석은 package-info.java 파일에 작성한다.
이 파일에는 패키지 선언을 반드시 포함해야 하는 패키지 선언 관련 애너테이션을 추가로 포함할 수 있다.
마지막으로 API 문서화에서 자주 누락되는 설명이 두 가지 있는데, 바로 스레드 안정성과 직렬화 가능성이다.
클래스 혹은 정적 메서드가 스레드 안전하든 그렇지 않든, 스레드 안전 수준을 반드시 API 설명에 포함해야 한다.
또한, 직렬화할 수 있는 클래스라면 직렬화 형태도 API 설명에 기술해야 한다.
