[Java] Javadoc

Javadoc 이해하기 📚

Javadoc은 Java 소스 코드에 포함된 특정 주석을 기반으로 표준화된 API 문서를 생성하는 도구입니다. 개발자가 작성한 소스 코드의 명세서, 클래스 및 메소드의 사용 방법, 매개변수와 반환 값의 의미 등 핵심 정보를 포함합니다.

Javadoc의 작동 원리 및 가치 ✨

Javadoc 주석은 일반 주석과 달리 컴파일 시점에 제거됩니다. 그러나 Javadoc 도구는 이 주석 내에 포함된 HTML 태그 (예: {@link}, <code>)를 해석하여 웹 브라우저에서 열람 가능한 HTML 형식의 API 문서를 생성합니다.

이러한 API 문서는 다음과 같은 가치를 제공합니다.

• 개발 협업 강화: 팀원 간 코드 이해도를 높여 효율적인 협업을 가능하게 합니다.
• 라이브러리 사용자 편의 증진: 외부에 공개되는 라이브러리나 프레임워크의 사용 방법을 명확하게 제시하여 사용자 진입 장벽을 낮춥니다.
• 코드 품질 향상: 명확한 문서화 요구사항은 개발자가 코드의 목적과 동작을 더 깊이 고민하게 하여 코드 품질 향상에 기여합니다.

Javadoc은 소스 코드와 함께 API 문서를 작성하는 가장 효과적인 방법 중 하나입니다.

주요 Javadoc 태그 분석 🏷️

Javadoc은 다양한 태그를 사용하여 코드 요소의 특성을 상세하게 설명합니다. 다음은 자주 사용되는 Javadoc 태그입니다.

태그	설명
@version	구현체(클래스, 메소드 등)의 버전 정보 명시
@author	구현체의 작성자
@deprecated	해당 구현체의 사용 중단을 권고하거나 삭제 예정임을 알림
@since	해당 구현체가 추가된 버전 또는 시점
@param	메소드 매개변수의 역할 및 의미 설명
@return	메소드 반환 값의 역할 및 의미 설명
@throws	메소드가 발생시킬 수 있는 예외 상황 정의

@see vs {@link} 🔎

두 태그 모두 다른 필드, 메소드, 클래스 또는 외부 문서에 대한 참조를 제공합니다.

• @see: "See Also" 섹션에 별도의 참조 링크를 생성합니다. 주로 관련 항목을 묶어 보여줄 때 사용합니다.
• {@link}: 주석 내용 내부에 인라인 하이퍼링크를 생성합니다. 특정 키워드에 대한 직접적인 참조가 필요할 때 유용합니다.

@exception vs @throws 🚨

@exception과 @throws는 동일한 목적으로 사용되며, 메소드가 발생시킬 수 있는 예외 상황을 정의합니다. @throws 태그 사용이 권장됩니다.

Javadoc 예시 📝

아래는 Javadoc 태그를 활용하여 메소드를 문서화한 예시입니다.

/**
 * 주어진 문자열을 처리하는 테스트 메소드입니다.
 *
 * @param abc 처리할 문자열
 * @return 처리된 문자열 결과
 * @throws Exception 문자열 처리 중 발생할 수 있는 일반 예외
 * @author 병갑
 */
public String Test(String abc) throws Exception {
    String asd = abc; // 실제 구현에서는 abc를 변환하는 로직이 있을 수 있습니다.
    return asd;
}

위 예시에서 @param abc, @return, @throws Exception 태그는 메소드의 구현 내용보다는 각 요소가 담당하는 역할과 의미를 명확히 설명합니다. 이는 해당 메소드를 사용하는 다른 개발자가 코드 내부 구현을 보지 않고도 쉽게 이해하고 활용할 수 있도록 돕습니다.

원문 출처: https://blog.naver.com/h970303/22315941087