Javadoc

전통적으로 API문서는 사람이 직접 작성하므로 코드가 변경되면 매번 함께 수정해줘야 하는데, 자바에서는 자바독(javadoc)이라는 유틸리티가 그러한 기능을 도와준다.
자바독은 소스코드 파일에서 문서화 주석이라는 특수한 형태로 기술된 설명을 추려 API 문서로 변환해준다.
문서화 주석을 작성하는 규칙은 공식 언어 명세에 속하진 않지만 자바 프로그래머라면 알아야 하는 업계 표준 API라 할 수 있다.
- 이 규칙은 문서화 주석 작성법(How to Write Doc Comments) 웹 페이지에 기술되어 있다.
  - 자바 4 이후로는 갱신되지 않은 페이지지만 그 가치는 여전하다.
자바 버전이 올라가며 추가된 중요한 자바독 태그는 다음과 같다
- 자바5 > @literal, @code
- 자바8 > @code, @implSpec
- 자바9 > @index

🎨 Javadoc 태그

@param : 매개변수가 뜻하는 명사구, 모든 매개변수의 설명을 작성한다.
@return : 반환 값을 설명하는 명사구, 반환 타입 void를 제외하고 설명을 작성한다.
@throws : 예외를 던지게 되는 조건 설명을 작성한다.
{@code} : 주석 내에 HTML 요소나 다른 자바독 태그를 무시한다.
- 주석에 코드를 여러줄을 추가하려면 <pre>{@code 코드~~~}</pre> 형태로 작성한다.
{@literal} : 주석 내에 HTML 요소나 다른 자바독 태그를 무시한다.
- <, >, &등의 HTML 메타문자를 포함시킨다.
- code와 비슷할 수 있지만 코드 폰트로 랜더링을 안한다.
@implSpec : 해당 메서드와 하위 클래스 사이를 계약을 설명한다.
- 하위 클래스들이 메서드를 상속하거나 super 키워드를 이용해 호출할 때 메서드가 어떻게 동작하는지 명확하게 인지할 수 있도록 해준다.
{@inheritDoc} : 상위 타입의 문서화 주석 일부를 상속할 수 있다.

javadoc -d docs {file_name}

# 한글을 사용할 경우에는 UTF-8로 인코딩이 필요합니다.
javadoc -d docs *.java -encoding UTF-8 -charset UTF-8 -docencoding UTF-8

Untitled