[Java] Item 56 : 공개된 API 요소에는 항상 문서화 주석을 작성하라

Effective Java를 읽고 정리한 정리본입니다.

📌 Item 56 : 공개된 API 요소에는 항상 문서화 주석을 작성하라

🫧 문서화 주석 작성

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

✨ 문서화 태그

1. @param
2. @return (void가 아닌 경우)
3. @throws (발생 가능성 있는 모든 예외)

관례상 param, return, throws 태그의 설명에는 마침표를 붙이지 않음.

문서화 주석에 HTML 태그를 쓰는데, 이때 {@code} 태그를 사용한다면 코드용 폰트로 렌더링할 수 있을 뿐만 아니라 태그로 감싼 내용에 포함된 HTML 요소나 다른 자바독 태그를 무시한다.

만일 문서화 주석에 여러 줄로 된 코드 예시를 넣으려면 {@code} 태그를 다시 <\pre> 태그로 감싸면 된다.

<pre>{@code ... 코드 ... }</pre>

단, @ 기호에는 무조건 탈출 문자를 붙어야 한다.

1. implSpec
   -> 일반적인 문서화 주석(메서드-클라이언트 사이) 과 달리, 해당 메서드와 하위 클래스 사이의 계약을 설명하여 하위 클래스들이 그 메서드를 상속하거나 super 키워드를 이용해 호출할 때 그 메서드가 어떻게 동작하는지를 명확히 인지하고 사용할 수 있도록 해 준다.

2. {@literal} : API 설명에 <, >, & 등의 HTML 메타문자를 포함시킬 때 사용

3. 요약 설명
   -> 각 문서화 주석의 첫 번째 문장은 요약 설명으로, 첫 번째 마침표 뒤 소문자가 아닌 문자가 오면 요약 설명이 끝났다고 판단하므로 마침표 사용에 주의하자.
   -> 자바 10부터는 {@summary} 라는 요약 설명 전용 태그가 추가되었다.

4. {@index}
5. 열거 타입 문서화 : 상수들에도 주석 달기
6. package-info.java : 패키지 설명 문서화 주석
7. module-info.java : 모듈 시스템 사용 설명
8. {@inheritDoc}
   -> 상위 타입 문서화 주석 일부를 상속