자바독(Javadoc)

API 문서는 사람이 직접 작성하기 때문에 코드가 변경되면 매번 함께 수정해주어야 한다.

자바에서는 자바독이라는 유틸리티가 해당 작업을 수행해준다.

https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html

자바독은 소스코드 파일에서 문서화 주석(doc comment)이라는 특수한 형태로 기술된 설명을 추려 API 문서로 변환하여 준다.

1. 문서화 주석

2. API 문서

⭐ 작성한 API를 올바르게 문서화하기 위해서는 공개된 모든 클래스, 인터페이스, 메서드, 필드 선언에 문서화 주석을 달아야 한다.

• 직렬화할 수 있는 클래스라면 직렬화 형태[아이템 87]에 관해서도 적어야 한다.
• 자바의 기본 생성자에는 문서화 주석을 작성할 수 없다.
  • 기본 생성자는 클래스에 명시적인 생성자가 하나도 정의되지 않은 경우에만 컴파일러가 자동으로 추가한다. 이 경우 기본 생성자가 코드에 명시적으로 나타나지 않기 때문에 문서화 주석을 작성할 수 없다.
  • 따라서 공개 클래스는 절대 기본 생성자를 사용하면 안 된다.
• 유지 보수를 위해 비공개 클래스, 인터페이스, 생성자, 메소드, 필드에도 문서화 주석을 달아야 한다.

⭐ 메서드용 문서화 주석에는 해당 메서드와 클라이언트 사이의 규약을 명료하게 기술해야 한다.

• 상속용으로 설계된 클래스[아이템 19]의 메서드가 아니라면 how가 아니라 what을 기술하여 무엇을 하는지를 기술해야 한다.
• 클라이언트가 해당 메서드를 호출하기 위한 전제조건(precondition)과 메서드가 성공적으로 수행된 후에 만족해야 하는 사후조건(postcondition) 모두 나열해야 한다.
  • 일반적으로 전제조건은 @throws 태그로 비검사 예외를 선언하여 암시적으로 기술한다.
  • 비검사 예외 하나가 전제조건 하나와 연결된다.
    • 검사 예외 vs 비검사 예외
  • 또한 @param 태그를 이용해 그 조건에 영향받는 매개변수에 기술할 수도 있다.