들어가며

API를 올바로 문서화하려면 공개된 모든 클래스, 인터페이스, 메소드, 필드 선언에 문서화 주석을 달아야한다. 자바독을 통하여 API 문서로 변환할 수 있다.

메소드 문서화

메소드용 문서화 주석에는 해당 메소드와 클라이언트 사이의 규약을 명료하게 기술해야 한다. 상속용으로 설계된 클래스의 메소드가 아니라면 그 메소드가 무엇을 하는지를 적어야한다. how가 아니라 what이다. 문서화 주석에는 클라이언트가 해당 메소드를 호출하기 위한 전제조건을 모두 나열해야 한다. 또한 메소드가 성공적으로 수행된 후에 만족해야 하는 사후조건도 모두 나열해야 한다. @throws 태그로 전제조건을, @param 태그로 조건에 영향받는 매개변수를 기술할 수 있다. 또한 사후조건에는 나타나지 않는 부작용도 기술해야 한다. 부작용이란 시스템 상태에 어떠한 변화를 가져오는 것이다. 메소드의 리턴 타입이 void가 아니라면 @return 태그를 통해 반환값을 작성해야 한다. 또한 코드를 기술하려면 {@Code} 태그를 이용할 수 있다.

클래스 문서화

클래스를 상속용으로 설계할 때는 자기사용패턴에 대해서도 문서화를 해야한다. @implSpec 태르르 통해 이를 알려줄 수 있다. 또한 특수한 기호들을 사용해야할 경우 {@literal} 태그로 이를 감싸면 된다.

요약 문서화

각 문서화 주석의 첫번째 문장은 해당 요소의 summary이다. summary는 마침표(.)에 주의해야한다. 이를 summary의 종료 요소로 판단하기 때문이다. 자바10 부터는 {@summary} 태그를 이용할 수 있지만 그 이하라면 {@literal} 태그를 이용해야 한다. summary는 해당 메소드나 생성자의 동작을 설명하는 주어가 없는 동사구여야 한다. 그리고 3인칭으로 기술한다.

검색 기능

자바9 부터는 검색기능이 추가되었다. {@index} 태그를 이용하면 된다.

제네릭 문서화

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

enum 문서화

열거 타입을 문서화할 때는 상수들에도 주석을 달아야 한다. 열거 타입 자체와 그 열거 타입의 public 메소드에도 마찬가지다.

애너테이션 문서화

애너테이션 타입을 문서화할 때는 멤버들에도 모두 주석을 달아야한다. 필드 설명은 명사구로 작성한다.

패키지와 모듈 문서화

패키지를 설명하는 문서화 주석은 pckage-info.java에 기술한다. 자바9 부터 지원하는 모듈 시스템도 이와 같다. module-info.java에 기술한다.

주의사항

클래스 혹은 정적 메소드가 thread-safe 하든 thread-unsafe하든 스레드 안전 수준을 API 설명에 포함해야 한다. 또한 직렬화할 수 있는 클래스라면 직렬화 형태도 API 설명에 기술해야 한다.

자바독은 메소드 주석의 상속이 가능하다. {@inheritDoc} 태그를 이용하면 된다. 자바독 검색 알고리즘은 상위 클래스보다 인터페이스를 우선시한다.

만약 전체적인 아키텍처를 설명하는 별도의 설명이 필요할 경우 관련 패키지나 클래스의 문서화 주석에서 아키텍처를 설명하는 문서의 링크를 제공해 주면 된다.