Javadoc이란?
Javadoc은 JDK와 함께 패키지로 제공되는 도구 입니다. JDK가 설치 되어있다면 Javadoc을 사용할 수 있으며, Java 소스 코드의 코드 문서를 생성하는데 도움을 주는 도구 입니다.
Javadoc의 사용법을 살펴보기전에 실제 Javadoc으로 생성된 문서를 한번 살펴보는 것을 추천합니다.
https://docs.oracle.com/javase/8/docs/api/
위 링크는 실제 javadoc으로 작성된 html 입니다. javadoc은 html을 따로 작성하지 않고도 소스 코드에 작성된 코멘트를 따라 문서를 만들 수 있게 됩니다. 또한 Javadoc에 따른 형식으로 작성해 두면 일반적인 주석으로 읽을 수 있을 정도로 아무런 위화감 없이 쉽고 간단한 형식으로 되어있습니다.
Javadoc 사용방법
cmd
cmd 창을 열고 java 파일이 있는 디렉토리로 이동 후 javadoc -d doc *.java 로 생성.
vscode
vscode extensions 에서 Javadoc Tools install 후 F1입력후 Javadoc Tools: Export Javadoc 으로 생성.
eclipse
프로젝트 Export클릭, Java -> Javadoc Next 클릭, Javadoc.exe 경로 설정 및 기타 설정후 export로 생성.
Javadoc의 대상이 되는 주석 작성방법
Javadoc을 이용하는 경우에도 Java 소스 코드에 작성하는 것과 차이가 없기 때문에 java 규칙을 따르지만, Javadoc 문서 생성의 대상으로하는 경우에는 다음과 같은 방법으로 작성해야합니다.
/**
주석
주석
*/
/** 주석 *//**에서 */까지 작성된 부분이 Javadoc의 대상이 됩니다.
시작이 /**이고 일반적인 주석의 작성 방법인 /*에 비해 *가 하나가 많지만, /* 이후 주석으로 *가 이어서 작성되고 있는 것과 동일하기에 Java에서의 주석인 것에는 변함이 없습니다.
또한 Javadoc에서는 여러 줄의 주석을 작성할 때는 각 줄 앞에 *가 작성되어 있던 경우는 제외하고 그 후에 문자열만을 주석의 대상으로 한다. 그리고 *이전에 작성된 공백이나 탭도 함께 제외된다. 따라서 Javadoc의 주석은 다음과 같은 작성 방법이 자주 사용됩니다.
/**
* 주석
* 주석
* 주석
*/위에 작성된 주석과 아래에 작성된 주석은 Javadoc에서 동일하게 처리됩니다.
/**
주석
주석
주석
*/Javadoc 문서 작성
public class Sample01 {
private int w;
private int h;
public Sample01() {
w = 0;
h = 0;
}
public void setSize(int width, int height) {
w = width;
h = height;
}
public int getWidth() {
return w;
}
public int getHeight() {
return h;
}
}위 일반적인 샘플코드에 대해서 Javadoc 주석을 작성한 예는 아래와 같습니다.
/**
* Javadoc 테스트용 클래스
*
* @author devkuma
* @version 1.0
*/
public class Sample01 {
/**
* 폭
*/
private int w;
/**
* 높이
*/
private int h;
/**
* 디폴트 생성자 클래스
*/
public Sample01() {
w = 0;
h = 0;
}
/**
* 사이즈 설정
*
* @param width 폭
* @param height 높이
*/
public void setSize(int width, int height) {
w = width;
h = height;
}
/**
* 폭 반환
*
* @return 폭
*/
public int getWidth() {
return w;
}
/**
* 높이 반환
*
* @return 높이
*/
public int getHeight() {
return h;
}
}주석 서식
주석의 구성
주석 안은 크게 나누면 '설명문'과 '태그 섹션' 이렇게 두 가지로 구분 할 수 있습니다. 설명문은 클래스 또는 메소드 등에 대해 간략하게 설명한 글이고, 설명문은 여러줄을 작성할 수 있습니다. 주석의 시작부분에서 첫번째 태그 섹션이 나타날 때까지가 설명문이 됩니다. 또한, Html문으로 해석되기 때문에 단순히 행을 바꿔 작성하여도 줄바꿈이 되지 않고 명시적으로 <br>을 작성해서 줄바꿈을 해야합니다.
/**
* 설명문 영역입니다.
* 여러 줄로 작성 할 수 있습니다.
* Html문으로 해석됨으로 <br> 등 Html태그 이용이 가능합니다.
* <a href="https://gochigo.kr" target="_blank">고치고</a>
* @version 2.0
* @author gochigolab
* @param String 이름
* @param int 시퀀스
*/위 주석은 * @version 2.0전까지 설명문 영역이며, 이후로는 '태그 섹션'으로 첫 번째 문자가 @로 시작합니다. '태그 섹션'은 하나의 주석에 여러 종류를 동시에 작성 할 수 있습니다. 또한 태그 섹션이 작성된 후에는 '설명문'을 작성 할 수 없습니다.
필드에 대한 주석 작성 시에 주의점
/**
* 폭과 높이를 나타낸다.
*/
int width, height;Java에서는 위와 같이 동일한 데이터 형식의 필드를 한번에 선언 할 수 있습니다. 하지만 Javadoc의 경우에는 아래와 동일하게 인식하여 Html이 작성되기 때문에 주의 해야합니다.
/**
* 폭과 높이를 나타낸다.
*/
int width;
/**
* 폭과 높이를 나타낸다.
*/
int heigth;Javadoc 태그
@author 태그
@author태그는 클래스, 인터페이스 등에 작성하고, 작성자를 지정하는데 사용합니다. 같은 주석 내에서 여러번 지정할 수 있습니다.
/**
* Javadoc 샘플 클래스
* @author ghochigolab
* @author xyrholl
*/
public class Sample02 {
/**
* 사이즈 설정
*
* @param width 폭
* @param height 높이
*/
public void setSize(int width, int height) {
}
}@version 태그
version태그는 클래스, 인터페이스 등에 작성하고 소프트웨어의 버전을 지정하기 위해 사용합니다. 같은 주석 내에서 여러번 지정 할 수 있습니다. 비슷한 태그로 @since가 있는데, 이 태그는 현재 버전이 아닌 도입 된 버전을 지정하는 경우에 사용합니다. 주의점은 Javadoc의 -version 옵션을 지정한 경우에만 출력이 됩니다.
/**
* Javadoc 샘플 클래스
*
* @version 1.0
* @version Project 1.0.1
*/
public class Sample03 {
/**
* 사이즈 설정
*
* @param width 폭
* @param height 높이
*/
public void setSize(int width, int height) {
}
}@see 태그
@see태그는 관련 항목으로 외부 링크 또는 텍스트를 표시하거나, 다른 필드나 메소드에 대한 모든 참조 링크를 나타내는 경우에 사용합니다. 즉, Html 문장의 <a>태그와 같은 형식으로 링크 및 레이블을 지정하여 사용합니다. 문자열을 표시할 경우에는 쌍따옴표("")를 둘러싸서 지정해야합니다.
/**
* Javadoc 샘플 클래스
*
* @see package.Class#field
* @see package.Class#method(Type, Type,...)
* @see package.Class#method(Type argname, Type argname,...)
* @see package.Class#constructor(Type, Type,...)
* @see package.Class#constructor(Type argname, Type argname,...)
* @see package.Class.NestedClass
* @see package.Class
* @see package
*
* @see "Java"
* @see <a href="http://gochigo.kr">고치고</a>
*/
public class Sample04 {
/**
* 사이즈 설정
*
* @param width 폭
* @param height 높이
* @see Sample04#getWidth()
* @see Sample04#getHeight()
*/
public void setSize(int width, int height) {
}
/**
* 폭 반환
*
* @return 폭
* @see Sample04#setSize(int, int)
* @see #getHeight()
*/
public int getWidth() {
return 0;
}
/**
* 높이 반환
*
* @return 높이
* @see Sample04#setSize(int, int)
* @see #getWidth()
*/
public int getHeight() {
return 0;
}
}@deprecated 태그
@ deprecated태그는 클래스나 메소드 등을 더 이상 사용을 권장하지 않는 경우에 사용합니다. 즉, 차후에 없어질 수도 있다는 것을 의미합니다.
/**
* Javadoc 샘플 클래스
*/
public class Sample05 {
/**
* 사이즈 설정
*
* @param width 폭
* @param height 높이
* @see Sample04#getWidth()
* @see Sample04#getHeight()
* @deprecated 다른 메소드로 대체되었다 {@link #setScale(int, int)}
*/
public void setSize(int width, int height) {
}
/**
* 사이즈 설정
*
* @param width 폭
* @param height 높이
*/
public void setScale(int width, int height){
}
}@param 태그
@param태그는 매개 변수에 대한 설명을 표시 할 때 사용합니다. 설명 부분은 여러 줄에 걸쳐 작성 할 수 있습니다. '설명문'과 동일하게 Html로 작성됩니다.
/**
* Javadoc 샘플 클래스
*/
public class Sample06 {
/**
* 사이즈 설정
*
* @param width 폭<br>
* 단위는 센티미터
* @param height 높이
*/
public void setSize(int width, int height) {
}
}@return 태그
@return태그는 반환 값에 대한 설명(데이터 유형 및 범위 등)을 표시 할 때 사용합니다.
/**
* Javadoc 샘플 클래스
*/
public class Sample07 {
/**
* 사이즈 설정
*
* @param width 폭
* @param height 높이
* @return 계산한 면적
*/
public int getSize(int width, int height) {
return width * height;
}
}@throws, @exception 태그
@throws @exception태그는 발생할 수 있는 예외에 대한 설명을 표시 할 때 사용합니다. 서로 이름만 다를뿐 동일하게 사용합니다.
import java.io.FileNotFoundException;
import java.io.IOException;
/**
* Javadoc 샘플 클래스
*/
public class Sample08 {
/**
* 파일 쓰기
*
* @throws FileNotFoundException 지정된 파일을 찾을 수 없습니다
*/
public void writeToFile() throws FileNotFoundException {
}
/**
* 파일 읽기
*
* @throws java.io.IOException 입출력 관련
* @throws java.lang.SecurityException 보안 관련
*/
public void readFromFile() throws IOException, java.lang.SecurityException {
}
/**
* 파일 삭제
*
* @throws java.lang.SecurityException 보안 관련
* @exception FileNotFoundException 지정된 파일을 찾을 수 없습니다
*/
public void deleteFile() throws SecurityException {
}
}{@link},{@linkplain} 태그
{@link} 태그는 다른 Javadoc 태그 중에 참조 링크를 표시 할 경우에 사용합니다. 지금까지의 태그들은 모두 블록 태그 라고 불리는 반면에 이 태그는 인라인 태그라고 하며, {}로 묶어 사용하는 주석을 설명문 안이나 다른 블록태그 안의 문자열의 부분에 사용할 수 있습니다.
{@linkplain}태그는 {@link}태그와 사용방법은 동일하며, 다른 Javadoc 태그에서 문자열을 표시 할 위치에 참조링크를 표시 할 경우에 사용합니다. {@link}태그를 사용하는 경우 연결 문자열은 코드 텍스트로 표시되는 반면, {@linkplain}태그의 경우는 링크가 된 문자열을 일반텍스트로 표시되는 점이 다릅니다.
/**
* Javadoc 샘플 클래스
*/
public class Sample09 {
/**
* 이름 설정
* 반환은 {@link Sample14#getName() getName}을 참조
*
* @param name 이름
*/
public void setName(String name){
}
/**
* 이름 반환
* 설정은 {@link #setName(String)}을 참조
*
* @return 이름을 String으로 반환
*/
public String getName(){
return null;
}
}@{code} 태그
{@code}태그는 Javadoc에 예제 코드 작성시 사용됩니다. 즉, 설명에 예제 코드를 첨부할 영역에 사용합니다.
/**
* Javadoc 샘플 클래스<br>
*
* <pre>
* {@code
* Foo foo = new Foo();
* foo.foo();
* }
* </pre>
*/
public class Sample10 {
}Javadoc 옵션지정
-d 옵션
-d 옵션은 생성 된 문서의 대상 디렉토리를 지정합니다.
$ javadoc -d {출력하는 디렉토리 혹은 대상 파일}-author 옵션
-author옵션은 생성된 문서에 @author태그로 지정된 저자를 출력하도록 지정합니다. "-author"옵션이 지정되지 않을 경우 @author태그가 주석에 작성이 되어 있어도 생성되는 문서에 저자는 출력되지 않습니다.
$ javadoc -author [대상 파일]-version 옵션
-version옵션은 생성된 문서에 @version태그로 지정된 버전을 출력하도록 지정한다.-version옵션이 지정되지 않을 경우 @version태그가 코멘트 중에 작성이 되어 있어도 생성되는 문서 버전은 출력되지 않는다.
$ javadoc -version [대상 파일]'Framework' 카테고리의 다른 글
| Spring Security (0) | 2022.04.04 |
|---|---|
| JNA(Java Native Access)란? (0) | 2022.03.31 |
| Javadoc 작성방법 (0) | 2022.03.30 |
| Logback 이란? (0) | 2022.03.29 |