Javadoc의 의미와 쓰는 방법 주석 다는 방법

Javadoc이란?

---

Javadoc은 간단히 설명하면 Java 언어 소스 코드에서 "프로그램을 설명하는 문서"를 생성하는 메커니즘입니다.

Javadoc용의 코멘트를 기술하면, 만든 프로그램에 대한 문서를 소스 코드에 묻어 줍니다.

구체적인 코드를 내고 상세하게 설명하겠습니다.

 

 

예를 들어, 값을 2배로 하여 결과를 출력하는 다음과 같은 프로그램이 있다고 합시다.

public class JavadocTest {  
 
   public static int doubleFunc ( int number ){  
      // 인수의 10을 두 배로 반환합니다.
      return number * 2 ; 
   }
 
   public static void main ( String [] args ){  
      // number에 double 함수의 결과를 할당합니다.
      int number = doubleFunc ( 10 );
      // 결과를 출력합니다.
      System . out . println ( number );
   }
 
}

 

이 소스 코드에 대해 컴퓨터는 다음 내용을 읽고 처리합니다.

 

1. 클래스의 명칭은 「JavadocTest」이다
2. ``JavadocTest''에는 메서드 'main'과 'double'이 있습니다.
3. 'main'은 'String[] args'를 받고 'void'를 반환합니다.
4. 'doubleFunc'는 'int number'를 받고 'int'를 반환합니다.

 

컴퓨터는 처리를 읽지만, 코멘트에 쓰여있는 내용이나 메서드의 내용은 프로그램에 따라 다르므로 보지 않습니다.

 

컴퓨터에 「이 코멘트는 문서에 실어 주세요」라고 판단시키기 위해서 사용되는 것이 「Javadoc용의 코멘트」가 됩니다.

 

 

Javadoc에 대한 주석 작성 방법

---

Javadoc에 대한 주석은 슬래시(/)와 별표(*)로 시작하는 '/**'로 작성됩니다.

/**
* 이것이 Javadoc에 대한 주석을 작성하는 방법입니다.
*/

 

이제 Javadoc에 대한 주석으로 인식됩니다.

 

또, Javadoc용의 코멘트중에 「@」는 특수한 기호로서 인식됩니다.

「@author」라고 기술하면 프로그램의 제작자를 의미하고, 「@version」라고 기술하면 버전을 의미한다고 하는 「Javadoc 태그」가 붙여집니다.

 

 

Javadoc용의 코멘트를 기술해, 값을 2배로 해 결과를 출력하는 프로그램의 소스 코드를 재기록하면, 다음과 같이 됩니다.

/**
* Javadoc용 주석 테스트 프로그램
* @author 포테판 스타일
* @version 1.0.0
*/
 
public class JavadocTest {  
 
   /**
   * doubleFunc 메소드
   * 인수를 2배로 돌려준다
   * @param number 정수 값
   * @return 인수를 두 배로 한 정수 값
   */
   public static int doubleFunc ( int number ){  
      // 인수의 10을 두 배로 반환합니다.
      return number * 2 ; 
   }
 
　　/**
   * main 메소드
   * double 메소드에 인수를 전달하고 결과를 출력합니다.
   */
   public static void main ( String [] args ){  
      // number에 double 함수의 결과를 할당합니다.
      int number = doubleFunc ( 10 );
      // 결과를 출력합니다.
      System . out . println ( number );
   }
 
}

Javadoc용의 코멘트를 추가한 이 소스 코드에 대해서, 컴퓨터는 이하의 내용을 읽어 처리를 합니다.

 

1. 클래스의 명칭은 「JavadocTest」이다
2. JavadocTest는 Javadoc 테스트 클래스입니다.
3. 「JavadocTest」를 만든 것은 「포테판 스타일」이다
4. JavadocTest 버전은 1.0.0입니다.
5. ``JavadocTest''에는 메소드 'main'과 'double'이 있습니다.
6. 'main'은 'String[] args'를 받고 'void'를 반환합니다.
7. 'main'은 'main 메소드'입니다.
8. 「main」은 「double 메서드에 인수를 건네주어 결과를 출력하는」 메서드이다
9. 'doubleFunc'는 'int number'를 받고 'int'를 반환합니다.
10. 'doubleFunc'는 'doubleFunc 메서드'입니다.
11. 「doubleFunc」는 「인수를 2배로 해 돌려주는」 메서드이다
12. 'doubleFunce'는 '정수 값'을 받습니다.
13. "doubleFunc"는 "인수를 두 배로 한 정수 값"을 반환합니다.

이상과 같이, Javadoc는 소스 코드로부터,

• 소스 코드의 구조에서 기계적으로 읽을 수 있는 것
• 특정 형식으로 작성된 댓글

의 2개를 자동으로 추출해 정리한 문서입니다.

이 문서를 작성할 때 사용되는 명령 프로그램이라고도 할 수 있습니다.

 

 

Javadoc 블록 태그의 종류와 의미

---

@author 이름	클래스나 인터페이스의 제작자 표시
@version 테스트	클래스나 인터페이스에서의 버전 정보
@param 매개변수 - 이름 설명	매개 변수에 대한 설명
@return 설명	메소드가 void를 리턴하거나 생성자가 아닌 경우를 제외하고 모두 사용해야 함
@exception or @throws	메소드가 발생시킬 수 있는 예외를 기술
@deprecated	다음 버전에서 폐기된 메소드를 알림
@serial	기본적으로 직렬화 할 수 있는 클래스의 멤버를 설명
@see	- 어떤 클래스, 인터페이스, 메소드, 생성자 혹은 URL에 대한 전후 참조 표시  - 분리된 줄에 링크가 생김
@since	Tag를 가진 객체가 언제 추가되었는지 명시
{@link #entity label}	메소드나 필드의 상호 참조에 대한 링크를 표시 문서 텍스트 안에 링크가 생김
{@doc-root}	문서에 대한 루트디렉토리에 대한 상대경로 지정

 

Javadoc 문서를 만드는 방법

---

Javadoc 명령을 사용하여 소스 코드에서 문서를 작성하는 경우 다음과 같이 실행하여 문서를 작성할 수 있습니다.

 

$javadoc - d html JavadocTest .

작성이 성공하면 html이라는 디렉터리가 작성되고 디렉터리에 'index.html'이라는 파일이 있습니다.

 

웹 브라우저에서 열고 내용을 확인하면 다음과 같은 HTML 형식의 문서가 생성됩니다.

 

 

블록태그 블럭태그