API 사용성을 늘리기 위해서는 잘 작성된 문서가 있어야 한다.
API 문서는 코드가 변경될 때마다 함께 수정해줘야 하기 때문에 문서화 주석 작성 규칙을 지켜 잘 작성해야 한다.
- 메서드용 문서화 주석에는 해당 메서드와 클라이언트 사이의 규약을 명료하게 기술한다.
@throws태그와@params태그를 이용해 상세한 기술 필요@return태그의 적절한 사용 필요
- API 설명에 HTML 메타 문자를 포함시킬 때 처리 주의
- API 문서의 가독성, 쉽고 이해하기 편하도록 설명 작성
- 한 클래스(or 인터페이스) 안에서 요약 설명이 똑같은 멤버(or 생성자)가 둘 이상이면 안된다.
- 제네릭 타입이나 제네릭 메서드를 문서화 할 때, 모든 타입 매개변수에 설명 주석 필요
- 열거 타입을 문서화 할 때, 상수들에도 반드시 주석 필요
- 어노테이션 타입 문서화 할 때, 멤버들에도 모두 주석 필요
- 스레드 안전성과 직렬화 가능성에 대한 설명을 누락해서는 안된다.
- 클래스 or 정적 메서드가 스레드 안전하든 그렇지 않든, 스레드 안전 수준을 반드시 API 설명에 포함시켜야 한다.
- 자바독 등을 문서를 올바르게 작성했는지 체크해야 한다.
- 자바독 유틸리티가 생성한 웹페이지를 읽어보면서 체크하기