API를 사용할 수 있으면 문서화해야합니다. 전통적으로 API 문서 코드를 수동으로 생성하고 코드와 동기화하여 유지하는 것은 힘든 일이었습니다.
자바 프로그래밍 환경은 Javadoc 유틸리티로이 작업을 용이하게합니다. Javadoc은 특별히 소스 코드에서 API 문서를 자동으로 생성합니다.
형식이있는 문서 주석 - 일반적으로 문서 주석으로 알려져 있습니다. 당신이 doc 주석 규정에 익숙하지 않다면, 그들. 이 규칙은 공식적으로 언어의 일부는 아니지만, 모든 프로그래머가 알아야 할 사실상의 API 이러한 규칙은 Sun의 문서 주석 작성 방법 웹 페이지 [Javadoc-guide]에 설명되어 있습니다.
이 페이지는 릴리스 1.4 이후로 업데이트되지 않았지만 여전히 가치가 있습니다
의지 2 개의 중요한 Javadoc 태그가 릴리스 1.5에서 Javadoc에 추가되었습니다.
{@literal} 및 {@code} [Javadoc-5.0] 이 태그는이 항목에서 설명합니다.
API를 올바르게 문서화하려면 내 보낸 모든 클래스 앞에 와야하며, 인터페이스, 생성자, 메서드 및 필드 선언에 doc 주석을 추가합니다.
만약 클래스가 직렬화 가능한 경우, 직렬화 된 형식 (항목 75)도 문서화해야합니다. 다큐 멘 테이션에서 코멘트가없는 경우, Javadoc가 할 수있는 최선은 선언을 재생성하는 것입니다.
영향을받은 API 요소에 대한 유일한 문서입니다. 그것은 실망스럽고 오류가 발생하여 문서 주석이 누락 된 API를 사용합니다. 유지 보수 가능을 작성하려면
코드를 사용하는 경우 대부분의 unexported 클래스에 대한 doc 주석을 작성해야합니다.
인터페이스, 생성자, 메서드 및 필드가 있습니다.
메서드에 대한 문서 주석은 계약을 간결하게 설명해야합니다. 메소드와 클라이언트 사이. 클래스의 메소드를 제외하고 상속을 위해 고안된 (Item 17) 계약은 메소드가하는 일을 말해야한다.
그것이 그 일을하는 방법보다는 오히려 문서 주석은 모든 메서드의 전제 조건은 클라이언트에서 순서대로 참이어야합니다.
그것을 호출하는 것, 그리고 그것들의 사후 조건들 호출이 성공적으로 완료되었습니다. 일반적으로 전제 조건이 설명됩니다.
체크되지 않는 예외에 대해 @throws 태그에 의해 암시 적으로; 각각의 검사되지 않은 예외 전제 조건 위반에 해당합니다. 또한 전제 조건을 지정할 수 있습니다.
@param 태그의 영향을받는 파라미터와 함께 전제 조건과 사후 조건 외에도 메소드는 문서화되어야한다.
부작용은 시스템 상태의 관찰 가능한 변화입니다. 그것은 사후 조건을 달성하기 위해 분명하게 요구되지는 않는다.
예를 들어, 메소드가 백그라운드 스레드를 시작하면 문서에 기록해 두어야합니다.
마지막으로 문서 주석은 클래스의 스레드 안전성을 설명해야합니다.
방법 (Item 70에서 논의 됨).