본문으로 이동

Javadoc

위키백과, 우리 모두의 백과사전.

Javadoc(자바독) 또는 JavaDoc, javadoc은 자바 프로그래밍 언어를 위한 API 문서 생성기이다. Javadoc은 자바 소스 코드의 정보를 바탕으로 HTML 형식 및 플러그인을 통한 다른 형식의 문서를 생성한다.[1] Javadoc은 썬 마이크로시스템즈에서 개발했으며 현재는 오라클이 소유하고 있다.

결과 문서의 내용과 형식은 소스 코드 주석 내의 특별한 마크업 언어를 통해 제어된다. 이 마크업은 자바 코드를 문서화하는 데 있어 사실상 표준이자 어디에나 존재하기 때문에,[2] 많은 통합 개발 환경(IDE)에서 소스 코드를 볼 때(종종 관련 심볼 위에 마우스를 올리는 방식으로) Javadoc 정보를 추출하여 표시한다. IntelliJ IDEA, 넷빈즈, Eclipse와 같은 일부 IDE는 Javadoc 템플릿 주석 블록 생성을 지원한다.[3] Javadoc 마크업의 @tag 구문은 Doxygen, JSDoc, EDoc, HeaderDoc 등 다른 문서 생성기에서도 재사용되어 왔다.

Javadoc은 doclets(도클릿)과 taglets(태그릿)을 통한 확장을 지원하며, 이를 통해 다양한 출력 형식을 생성하거나 코드베이스의 정적 분석을 수행할 수 있다. 예를 들어, JDiff는 API의 두 버전 간 변경 사항을 보고한다.

일부에서는 Javadoc과 일반적인 API 문서 생성기를 비판하기도 하지만, Javadoc을 만든 동기 중 하나는 전통적인(자동화가 덜 된) API 문서가 전문 기술 작가의 부족과 같은 비즈니스적 제약으로 인해 종종 구식이 되거나 존재하지 않는 경우가 많았기 때문이다.[4]

Javadoc은 첫 출시 때부터 자바의 일부였으며, 자바 개발 키트의 각 릴리스와 함께 자주 업데이트된다.[5]

Javadoc과 Javadoc이 사용하는 소스 코드 주석은 컴파일러에 의해 무시되므로 자바 실행 파일의 성능에 영향을 주지 않는다.

마크업

[편집]

Javadoc은 특별히 표시되지 않은 주석은 무시한다. Javadoc 주석은 다중 행 주석의 시작 부분에 별표를 하나 더 추가하여 /**로 표시한다. 이어지는 줄은 *로 시작하며, 전체 주석 블록은 */로 끝나야 한다.

메서드 Javadoc 주석의 예시는 다음과 같다:

/**
 * 메서드가 수행하는 작업에 대한 설명.
 *
 * @param input 매개변수에 대한 설명.
 * @return 반환값에 대한 설명.
 * @throws Exception 예외에 대한 설명.
 */
public int methodName(String input) throws Exception { ... }

Javadoc에서는 <p>, <head>, <nav>와 같은 일부 HTML 태그를 지원한다.

마크다운

[편집]

자바 23부터 Javadoc은 기존의 다중 행 형식 대신 ///로 시작하는 주석 줄에서 마크다운 표준인 CommonMark를 지원한다.[6]

도클릿

[편집]

도클릿(Doclet) 프로그램은 Javadoc과 연동하여 문서에 포함할 콘텐츠를 선택하고, 콘텐츠의 프레젠테이션 형식을 지정하며, 문서를 포함하는 파일을 생성한다.[7] 도클릿은 자바로 작성되며 Doclet API을 사용한다.

Javadoc에 포함된 StandardDoclet은 API 문서를 프레임 기반의 HTML 파일로 생성한다. 웹상에서 다른 도클릿들도 이용 가능하며, 종종 무료로 제공된다. 이들은 다음과 같은 용도로 사용될 수 있다:

  • 다른 유형의 문서 생성 (비 API용)
  • PDF와 같이 HTML 이외의 형식으로 출력
  • 검색 기능이나 자바 클래스에서 생성된 UML 다이어그램이 포함된 추가 기능을 갖춘 HTML로 출력

태그

[편집]

사용 가능한 일부 Javadoc 태그[8] 목록은 아래 표와 같다:

구문 사용법 적용 대상 도입 버전
@author name"Pat Smith"와 같은 저자를 식별클래스, 인터페이스, 열거형
{@docRoot} 생성된 모든 페이지에서 생성된 문서의 루트 디렉터리에 대한 상대 경로를 나타냄 클래스, 인터페이스, 열거형, 필드, 메서드
@version version버전 정보모듈, 패키지, 클래스, 인터페이스, 열거형
@since since-text이 기능이 처음 존재하기 시작한 시기를 설명클래스, 인터페이스, 열거형, 필드, 메서드
@see reference문서의 다른 요소로 링크클래스, 인터페이스, 열거형, 필드, 메서드
@param name description메서드 매개변수를 설명메서드
@return description반환값을 설명메서드
@exception classname description
@throws classname description		이 메서드에서 발생할 수 있는 예외를 설명메서드
@deprecated description메서드가 구식임을 표시클래스, 인터페이스, 열거형, 필드, 메서드
{@inheritDoc}오버라이드된 메서드로부터 설명을 복사오버라이딩 메서드1.4.0
{@link reference}다른 심볼로의 링크클래스, 인터페이스, 열거형, 필드, 메서드
{@linkplain reference} {@link}과 동일하지만 링크의 레이블이 코드 글꼴이 아닌 일반 텍스트로 표시됨 클래스, 인터페이스, 열거형, 필드, 메서드
{@value #STATIC_FIELD}정적 필드의 값을 반환정적 필드1.4.0
{@code literal}리터럴 텍스트를 코드 글꼴로 서식화. {@literal}과 동일함클래스, 인터페이스, 열거형, 필드, 메서드1.5.0
{@literal literal}리터럴 텍스트를 나타냄. 포함된 텍스트는 HTML 마크업이나 중첩된 javadoc 태그를 포함하지 않는 것으로 해석됨클래스, 인터페이스, 열거형, 필드, 메서드1.5.0
{@serial literal} 기본적인 직렬화 가능 필드를 나타냄 필드
{@serialData literal} writeObject( ) 또는 writeExternal( ) 메서드에 의해 기록된 데이터를 나타냄 필드, 메서드
{@serialField literal} ObjectStreamField 구성 요소를 나타냄 필드

같이 보기

[편집]

각주

[편집]
  1. ↑ “Javadoc”. 《agile.csc.ncsu.edu》. 2017년 6월 13일에 원본 문서에서 보존된 문서. 2022년 1월 12일에 확인함.
  2. ↑ “javadoc - The Java API Documentation Generator”. Sun Microsystems. 2011년 9월 30일에 확인함..
  3. ↑ IntelliJ IDEA, NetBeans 보관됨 2017-04-05 - 웨이백 머신 and Eclipse
  4. ↑ Venners, Bill; Gosling, James 외 (2003년 7월 8일). “Visualizing with JavaDoc”. artima.com. 2013년 1월 19일에 확인함. When I did the original JavaDoc in the original compiler, even the people close around me pretty soundly criticized it. And it was interesting, because the usual criticism was: a good tech writer could do a lot better job than the JavaDoc does. And the answer is, well, yeah, but how many APIs are actually documented by good tech writers? And how many of them actually update their documentation often enough to be useful?
  5. ↑ “How to Write Doc Comments for the Javadoc Tool”. Sun Microsystems. 2011년 9월 30일에 확인함..
  6. ↑ “JEP 467: Markdown Documentation Comments”. 《OpenJDK》. 2023년 9월 11일. 2025년 9월 10일에 확인함.
  7. ↑ “Doclet Overview”.
  8. ↑ JavaSE 13 Documentation Comment Specification

외부 링크

[편집]
원본 주소 "https://ko.wikipedia.org/w/index.php?title=Javadoc&oldid=41173667"