자바독

Javadoc

자바독(원래는 JavaDoc으로 표기)[1]은 Java 언어(현재 Oracle Corporation 소유)용으로 Sun Microsystems가 작성한 문서 생성기로, Java 소스 코드에서 HTML 형식의 API 문서를 생성합니다.HTML 형식은 관련 문서를 [2]하이퍼링크로 연결할 수 있는 편리함을 추가하기 위해 사용됩니다.

Javadoc에서 사용하는 "doc comments" 형식은[3] Java 클래스를 문서화하기 위한 사실상의 업계 표준입니다.IntelliJ IDEA,[4] NetBeans, Eclipse와 같은 일부 IDE는 자동으로 Javadoc HTML을 생성합니다.많은 파일 에디터는 사용자가 Javadoc 소스를 만드는 것을 지원하며 Javadoc 정보를 프로그래머의 내부 참조로 사용합니다.

Javadoc은 또한 사용자가 Java 응용 프로그램의 구조를 분석할 수 있는 도큐렛과 태그렛을 만들기 위한 API를 제공합니다.이것이 JDiff가 API의 두 버전 간에 변경된 사항에 대한 보고서를 생성하는 방법입니다.

자바독은 컴파일 시 모든 코멘트가 삭제되므로 Java의 퍼포먼스에 영향을 주지 않습니다.코멘트와 Javadoc을 작성하는 것은 코드를 더 잘 이해하고 유지 보수하기 위한 것입니다.

역사

Javadoc은 초기 Java 언어 문서 [5]생성기입니다.문서 생성기를 사용하기 전에는 일반적으로 [6]소프트웨어용 독립형 문서만 작성하는 기술 문서를 사용하는 것이 일반적이지만 이 문서를 소프트웨어 자체와 동기화하는 것은 훨씬 더 어려웠습니다.

Javadoc은 첫 번째 릴리스부터 Java에 의해 사용되어 왔으며, 보통 Java Development Kit의 새로운 릴리스마다 업데이트됩니다.

그@fieldJavadoc 구문은 크로스 언어 Doxygen, JavaScript용 JSDoc 시스템, Apple HeaderDoc 등 다른 언어의 문서 시스템에 의해 에뮬레이트되었습니다.

기술 아키텍처

Javadoc 코멘트 구조

Javadoc 코멘트는 표준 복수 행 코멘트 태그에 의해 코드에서 소거됩니다./*그리고.*/시작 태그(begin-comment delimiter라고 함)에는 다음과 같이 추가 아스타리스크가 있습니다./**.

  1. 첫 번째 단락은 문서화된 방법에 대한 설명입니다.
  2. 다음 설명에는 다양한 수의 설명 태그가 있습니다.
    1. 메서드의 파라미터(@param)
    2. 메서드에 의해 반환되는 것(@return)
    3. 메서드에 의해 발생할 수 있는 예외(@throws)
    4. 기타 일반적이지 않은 태그:@see('도 참조' 태그)

자바독의 개요

문서 코멘트 작성의 기본 구조는 코멘트를 내장하는 것입니다./** ... */Javadoc 댓글 블록은 항목 바로 위에 배치되며 줄 바꿈은 없습니다.모든 Import 문은 클래스 선언 앞에 와야 합니다.클래스 선언에는 일반적으로 다음이 포함됩니다.

// 문의 Import  /** * @author Firstname 성 <address@example.com> * @version 1.6(프로그램의 현재 버전 번호) * 1.2 이후 (이 클래스가 처음 추가된 패키지 버전) */ 일반의 학급 시험 {     // 클래스 본문 }

방법의 경우 (1) 항목의 기능을 설명하는 짧고 간결한 한 줄의 설명이 있다.그 뒤에 (2) 여러 단락에 걸친 긴 설명이 이어진다.자세한 내용은 이쪽에서 자세히 설명하겠습니다.이 섹션은 옵션입니다.마지막으로, (3) 태그 섹션이 있어, 받아들여진 입력 인수와 메서드의 반환치를 일람표시한다.자바독은 모두 HTML로 취급되므로 여러 단락 섹션은 ""로 구분됩니다.<p>" 단락 구분 태그. 

/** * 한 줄의 짧은 설명 (1) * <p> * 설명이 길어집니다.만약 있다면, 그것은 (2)가 될 것이다. * 여기 있습니다. * <p> * 더 많은 설명이 연속적으로 이어집니다. * HTML 패러그래프로 구분된 패러그래프 * * @param variable 설명 텍스트 (3) * @return 설명 텍스트 텍스트. */ 일반의 인트 메서드명 (...) {     // 리턴 문이 있는 메서드 본문 }

변수들은 파트 (3)이 생략된 것을 제외하고 방법과 유사하게 문서화된다.이 변수에는 간단한 설명만 포함되어 있습니다.

/** * 변수에 대한 설명입니다. */ 사적인 인트 디버깅 = 0;

단일 문서 설명에 여러 변수를 정의하는 것은 권장되지[7] 않습니다.이는 Javadoc이 각 변수를 읽고 생성된HTML 페이지에 모든 필드에 대해 복사된 문서 설명과 함께 별도로 배치하기 때문입니다. 

/** * 점의 수평 및 수직 거리(x,y) */ 일반의 인트 x, y;      // 피하다

대신 각 변수를 따로 작성하여 문서화하는 것이 좋습니다.

/** * 점의 수평 거리입니다. */ 일반의 인트 x;  /** * 점의 수직 거리입니다. */ 일반의 인트 y;

자바독 태그 표

사용 가능한 Javadoc 태그의 일부를[8] 아래 표에 나타냅니다.

태그와 파라미터 사용. 적용 대상 부터
@author 존 스미스 작성자에 대해 설명합니다. 클래스, 인터페이스, 열거
{@docRoot} 생성된 페이지에서 생성된 문서의 루트 디렉토리에 대한 상대 경로를 나타냅니다. 클래스, 인터페이스, 열거, 필드, 메서드
@version 버전 소프트웨어 버전엔트리를 제공합니다.클래스 또는 인터페이스당 최대 1개입니다. 클래스, 인터페이스, 열거
@이후 이후 텍스트 이 기능이 처음 존재하는 시기를 설명합니다. 클래스, 인터페이스, 열거, 필드, 메서드
@ 참조 언급 문서의 다른 요소에 대한 링크를 제공합니다. 클래스, 인터페이스, 열거, 필드, 메서드
@parames(@parames) 이름 설명 메서드 파라미터에 대해 설명합니다. 방법
@return 묘사 반환값에 대해 설명합니다. 방법
@parames(@parames) 클래스명 설명
@parames(@parames) 클래스명 설명		 이 메서드에서 발생할 수 있는 예외에 대해 설명합니다. 방법
@권장되지 않았다 묘사 오래된 메서드를 설명합니다. 클래스, 인터페이스, 열거, 필드, 메서드
{@inheritDoc} 재정의된 메서드에서 설명을 복사합니다. 덮어쓰기 방법 1.4.0
{@link} 다른 기호로 링크합니다. 클래스, 인터페이스, 열거, 필드, 메서드
{@linkplain} {@link}과(와) 동일하지만 링크의 라벨이 코드 글꼴이 아닌 일반 텍스트로 표시됩니다. 클래스, 인터페이스, 열거, 필드, 메서드
{@value #STATIC_FILD} 정적 필드의 값을 반환합니다. 정적 필드 1.4.0
{@code 리터럴} 코드 글꼴의 리터럴텍스트 형식을 지정합니다.<code> {@literal} </code>에 해당합니다. 클래스, 인터페이스, 열거, 필드, 메서드 1.5.0
{@module 리터럴} 리터럴 텍스트를 나타냅니다.동봉된 텍스트는 HTML 마크업 또는 중첩된 javadoc 태그를 포함하지 않는 것으로 해석됩니다. 클래스, 인터페이스, 열거, 필드, 메서드 1.5.0
{@module 리터럴} 기본 직렬화 가능 필드에 대한 문서 설명에서 사용됩니다. 들판
{@serialData 리터럴} writeObject() 또는 write에 의해 쓰여진 데이터를 문서화합니다.외부() 메서드. 필드, 방법
{@serialField 리터럴} ObjectStreamField 구성 요소를 문서화합니다. 들판

예

다음은 방법을 문서화하는 Javadoc의 예입니다.이 예에서는 공백과 글자 수는 표기법 상태와 같습니다. 

/** * 체스 동작을 확인합니다. * * <p> 조각을 이동하려면 {@link #doMove(int from File, int from Rank, int to File, int to Rank)}를 사용합니다. * * 조각이 이동되는 파일의 @param * @param from Piece 이동원 순위 * @param to File 파일을 이동할 수 있습니다. * @param toRank의 피스 이동처 순위 * 이동이 유효하면 @return true, 그렇지 않으면 false * 1.0 이후 */ 부울 is Valid Move(유효 이동)(인트 파일로부터, 인트 순위에서, 인트 파일링, 인트 순위) {     // ...본문 }  /** * 체스 피스를 이동합니다. * * @java.math 참조.반올림 모드 */ 무효 이동(인트 파일로부터, 인트 순위에서, 인트 파일링, 인트 순위)  {     // ...본문 }

「 」를 참조해 주세요.

레퍼런스

  1. ^ 이제 'Javadoc'으로 표기됩니다.[1]을 참조해 주세요.원래 이름은 'JavaDoc'입니다.'2' 참조
  2. ^ "Archived copy". agile.csc.ncsu.edu. Archived from the original on 13 June 2017. Retrieved 12 January 2022.{{cite web}}: CS1 maint: 제목으로 아카이브된 복사(링크)
  3. ^ 를 클릭합니다"javadoc - The Java API Documentation Generator". Sun Microsystems. Retrieved 2011-09-30..
  4. ^ IntelliJ IDEA, NetBeans 2017-04-05 Wayback Machine and Eclipse 아카이브 완료
  5. ^ 를 클릭합니다"How to Write Doc Comments for the Javadoc Tool". Sun Microsystems. Retrieved 2011-09-30..
  6. ^ Venners, Bill; Gosling, James; et al. (2003-07-08). "Visualizing with JavaDoc". artima.com. Retrieved 2013-01-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?
  7. ^ "Java Platform, Standard Edition Tools Reference for Oracle JDK on Solaris, Linux, and OS X, Release 8. Section "Multiple-Field Declarations"". Retrieved 20 Dec 2017.
  8. ^ JavaSE 13 문서 주석 사양

외부 링크