Javadoc은 Java 소스 코드에서 HTML 형식으로 API 문서를 생성하기 위해 Sun Microsystems에서 Java 언어용으로 만든 문서 생성기입니다.
Javadoc 형식의 주석은 모듈, 패키지, 클래스, 인터페이스, 생성자, 메서드, 열거형 멤버 또는 필드 선언 바로 앞에 배치될 때만 인식됩니다. 메서드 본문에 배치된 Javadoc 주석은 무시됩니다. 선언문 당 하나의 Javadoc 주석만 인식됩니다.
Javadoc 주석의 전체 형식은 초기 주요 설명으로 시작하여 해당 주석이 적용되는 선언에 대한 추가 정보를 제공하는 일련의 블록 태그로 이어집니다. 설명 텍스트에는 아래에 설명된 인라인 태그와 HTML 콘텐츠가 포함될 수 있습니다. 각 줄의 시작 부분의 선행 공백과 asterisks(*)는 무시됩니다.
블록 태그만 있고 본 설명이 없는 Javadoc 주석을 가질 수도 있습니다.
역사적인 이유로 패키지에 대한 Javadoc 주석은 대신 패키지의 소스 디렉토리에 있는 package.html이라는 파일에 제공될 수 있습니다. 이 경우, Javadoc 주석은 <body> 태그의 내용이며, Java 유형에 대한 모든 참조(예: @see 태그에서)는 완전한 자격 이름으로 지정되어야 합니다. 표준 독립형 문서 생성 도구(doclet)는 또한 overview.html과 같은 파일에 추가 문서를 제공할 수 있습니다. 이러한 콘텐츠에 대한 규칙은 package.html의 경우와 동일합니다.
블록 태그는 @identifier content 형식으로 되어 있으며, 생성된 문서에 통합될 추가 세부 정보를 제공합니다. 각 블록 태그는 줄의 시작에 나와야 하며, 선행하는 별표, 공백 문자, 그리고 초기 주석 구분자 (/**)는 무시됩니다. 이는 텍스트의 다른 곳에서 @ 문자를 사용해도 태그의 시작으로 해석되지 않는다는 것을 의미합니다. @ 문자로 시작하는 줄을 시작하고 싶지만 해석되지 않게 하려면 HTML 엔터티 @을 사용하세요. 블록 태그의 내용은 태그 다음부터 시작하여 다음 블록 태그나 문서 주석의 끝까지인 임의의 텍스트입니다. 내용은 여러 줄에 걸칠 수 있습니다.
블록 태그의 수에는 제한이 없으며, 일부 태그 유형은 반복될 수 있지만 다른 것들은 반복될 수 없습니다.
인라인 태그는 {@identifier content} 형식으로 되어 있으며, 둘러싸는 설명의 맥락 안에서 세부 정보를 제공합니다. 일반적으로 설명 텍스트와 HTML이 허용되는 곳에 나타날 수 있지만, 일부 인라인 태그는 주로 주요 설명의 시작 부분에서만 사용할 수 있습니다.
일부 인라인 태그에는 자유 형식의 텍스트가 포함될 수 있습니다. 이러한 텍스트에 중괄호가 명시적으로 포함된 경우, 중괄호는 "균형잡힌" 상태여야 하며, 따라서 인라인 태그의 닫는 중괄호를 결정할 수 있어야 합니다. 텍스트의 다른 렉시컬 분석은 수행되지 않습니다. 특히 ', ", \ 및 @ 같은 문자에 대한 특별한 고려가 없습니다.
인라인 태그 내에 포함된 @로 시작하는 줄은 블록 태그의 시작으로 간주되지 않습니다.
텍스트 내용이 HTML인 경우, 균형이 맞지 않는 중괄호를 나타내기 위해 엔터티 { 및 }를 사용할 수 있습니다.
| Tag | Description | Introduced in JDK |
|---|---|---|
| @author | -author name-text라고 지정한 이름 텍스트와 함께 "작성자" 항목을 생성합니다. -author 옵션이 사용될 때 생성된 문서에 여러 @author 태그가 포함될 수 있습니다. 각 @author 태그 당 하나의 이름을 지정하거나 태그 당 여러 이름을 지정할 수 있습니다. 이전 경우에는 표준 doclet이 이름 사이에 쉼표(,)와 공백을 삽입합니다. 후자의 경우 전체 텍스트가 구문 분석되지 않고 생성된 문서에 복사됩니다. 따라서 쉼표 이외의 로컬화된 이름 구분자를 사용하려면 한 줄에 여러 이름을 사용할 수 있습니다. | 1.0 |
| {@code} | -HTML 태그나 중첩된 Javadoc 태그를 해석하지 않고 코드 글꼴로 텍스트를 표시합니다. -즉, 문서 주석에서 일반적인 각도 괄호(< 및 >) 대신 HTML 엔터티(< 및 >)를 사용할 수 있습니다. -이는 매개 변수 유형(<Object>), 부등식(3 < 4) 또는 화살표(->)와 같은 문서 주석에서 일반적으로 사용되는 경우에 유용합니다. | 1.5 |
| @deprecated | -이 태그는 @Deprecated 주석과 함께 사용되어 더 이상 사용되지 않아야 함을 나타냅니다. -주석의 첫 문장은 API가 폐기된 시기와 대체 제품으로 사용할 항목을 사용자에게 알려야 합니다. -주석의 첫 문장은 요약 섹션과 색인에 복사됩니다. | 1.1 |
| {@docRoot} | -생성된 문서의 루트 디렉터리로부터 생성된 문서의 상대 경로를 나타냅니다. -모든 생성된 페이지에서 참조할 파일(저작권 페이지 또는 회사 로고와 같은)을 포함하려는 경우 유용합니다. | 1.4 |
| @exception | -@throws 태그와 동등합니다. | 1.0 |
| @hidden | -생성된 API 설명서에서 프로그램 요소를 숨깁니다. -API를 설계할 때 이러한 항목이 전혀 표시되지 않게하는 것이 불가능한 경우에 사용할 수 있습니다. | 1.3 |
| {@index} | -생성된 문서에서 생성된 색인 파일에 나타날 단어 또는 구문 및 선택적 짧은 설명을 선언합니다. -색인 항목은 생성된 문서에서 이 시점에 나타나는 단어 또는 구문에 연결됩니다. -어떤 단어 또는 구문을 인덱싱할지 명확하지 않은 경우에 설명을 사용할 수 있습니다. | 1.2 |
| {@inheritDoc} | -가장 가까운 상속 가능한 클래스 또는 구현 가능한 인터페이스에서 현재 설명 주석으로 상속(복사)합니다. -이 태그는 메서드의 메인 설명, @return, @param 및 @throws 태그의 텍스트 인수에만 유효합니다. -이 태그가 누락된 경우 설명은 상속 또는 상속되지 않습니다. | 1.4 |
| {@link} | -참조 된 클래스의 모듈, 패키지, 클래스 또는 멤버 이름에 대한 설명을 나타내는 가시적 텍스트 레이블이 포함된 인라인 링크를 삽입합니다. -모든 설명 주석에서 유효합니다. | 1.0 |
| {@linkplain} | -링크 레이블이 코드 글꼴 대신 일반 텍스트로 표시되는 {@link} 태그와 동일하지만 {@linkplain} 태그로 링크를 생성합니다. -레이블이 일반 텍스트인 경우 유용합니다. | 1.5 |
| {@literal} | -HTML 마크업 또는 중첩 된 Javadoc 태그를 해석하지 않고 텍스트를 표시합니다. -괄호 (<및>) 대신 HTML 엔터티 (<및>)를 사용할 수 있습니다. -예를 들어, 생성된 HTML 페이지에서 {@literal A<B>C}는 A<B>C로 변경되지 않고 표시됩니다. | 1.0 |
| @param | -"매개 변수" 섹션에 지정된 매개 변수 이름과 설명을 추가합니다. -설명은 여러 줄로 계속될 수 있습니다. -메서드, 생성자 또는 클래스의 문서 주석에서만 유효합니다. | 1.0 |
| @provides | -모듈 선언의 문서 주석에만 나타날 수 있으며, 모듈이 제공하는 서비스의 구현을 문서화합니다. -설명을 사용하여이 서비스 제공자의 인스턴스를 얻는 방법과 제공자의 중요한 특성을 지정할 수 있습니다. | 1.9 |
| @return | -"반환" 섹션에 주어진 설명을 추가하여 메서드가 반환하는 값에 대한 자세한 내용을 제공합니다. -메서드 설명 주석에서만 사용됩니다. | 1.0 |
| @see | -참조 항목에 링크 또는 텍스트 항목을 포함하는 "참조 항목" 제목을 추가합니다. -이 태그를 사용하면 다른 API 요소로 링크를 제공할 수 있습니다. | 1.0 |
| @serial | -기본 Serializable 필드의 설명 주석에 사용됩니다. -기본 Serializable 필드는 static이 아니며 transient이며 클래스에서 Serializable을 구현하고 ObjectStreamField와 관련이 없으며 직렬화된 스트림에 기록됩니다. -이 태그는 일반적으로 객체 직렬화에 대한 사용법에 대한 문서 설명을 포함합니다. | 1.0 |
| @serialData | -직렬화 된 형태의 데이터 유형 및 순서를 문서화합니다. -메서드 또는 생성자 설명 주석에서만 사용됩니다. | 1.2 |
| @serialField | -Serializable 클래스의 serialPersistentFields 멤버에서 ObjectStreamField 구성 요소를 문서화합니다. -Serializable 클래스의 인스턴스를 직렬화 할 때 이러한 필드를 포함하여 직렬화된 스트림에 기록됩니다. -이 태그는 객체 직렬화에 대한 사용법에 대한 문서 설명을 포함합니다. | 1.2 |
| @since | -생성된 문서에 지정된 이후 텍스트 값과 함께 "이후" 제목을 추가합니다. -지정된 이후 텍스트는 생성된 문서에 추가로 전달되고 버전 섹션에 표시됩니다. | 1.1 |
| @snippet | -생성된 설명서에 예제 코드의 조각 또는 "스니펫"을 포함시킵니다. | 1.4 |
| @spec | -외부 사양을 식별합니다. -사양은 URL 및 제목으로 식별됩니다. -이 태그는 생성된 문서의 "참조" 페이지에 나타납니다. -사양을 참조하여 메서드의 동작을 설명하는 것이 좋습니다. | 1.1 |
| {@summary} | -API 설명의 요약을 식별합니다. -이것은 API 설명의 첫 번째 문장 대신 사용됩니다. -이것은 기본적으로 각 API 설명의 첫 번째 문장이지만 사용자가 문서 주석에 독립적으로 지정할 수 있습니다. | 1.2 |
| {@systemProperty} | -property-name을 시스템 속성 이름으로 식별합니다. -이 속성 이름은 java 시스템 속성 이름으로 해석됩니다. -설명은 속성이 런타임 시 시스템에서 어떻게 사용되는지에 대해 자세히 설명해야합니다. | 1.8 |
| @throws | -"예외" 섹션에 주어진 이름과 설명을 추가하여 메서드에서 throw 할 수있는 예외에 대한 자세한 내용을 제공합니다. -메서드 설명 주석에서만 사용됩니다. | 1.0 |
| @uses | -모듈 선언의 문서 주석에만 나타날 수 있으며, 모듈이 서비스를 사용할 수 있음을 나타냅니다. -설명을 사용하여 서비스를 사용하는 방법과 서비스 사용의 중요한 특성을 지정할 수 있습니다. | 1.6 |
| {@value} | -컴파일 타임 상수 값을 갖는 정적 필드의 값이 표시됩니다. -이 필드가 메서드에 속해 있으면 값을 반환하지 않습니다. -이 필드가 클래스에 속해 있으면 값이 반환됩니다. -프로그램 요소가 생성된 문서의 메서드나 생성자 주석에 있으면 {@value} 태그는 값을 인라인으로 표시합니다. | 1.4 |
| @version | -생성된 문서에 지정된 버전 텍스트 값과 함께 "버전" 하위 제목을 추가합니다. -지정된 버전 텍스트는 생성된 문서에 추가로 전달되고 버전 섹션에 표시됩니다. | 1.0 |