[Java] JavaDoc으로 문서화 하기 (문서 생성하기, lombok으로 생성된 메소드까지 문서화 하기)

Java에는 Javadoc이라는 문서화 툴이 있어서 문서를 쉽게 만들 수 있다.
사용법은 간단하다. 변수, 메소드, 클래스 선언부 바로 위에 /**로 시작하는 여러줄 주석을 달면 된다.
/** 까지만 치면 인텔리제이가 알아서 자동완성해준다.

패키지 주석은 해당 패키지에 package-info.java라는 파일을 만들고 그 파일에 주석을 달면 된다.
인텔리제이에서는 패키지에 오른쪽 마우스를 클릭하고 New를 누르면 package-info.java를 만들 수 있게 되어있다.

그러면 이렇게 생겼을 것이다.

이 코드 위에 여러줄 주석으로 패키지에 대한 설명을 달면 된다.

클래스 주석은

이렇게 달면 된다.
만약 lombok과 같은 어노테이션이 있다면 아래와 같이 어노테이션 위에 주석을 달면 된다.

메소드 주석은

이렇게 달면 된다. 메소드를 완성하고 /** 까지만 치면 @param, @return, @throws까지 자동으로 만들어준다.
맨 위에는 메소드에 대한 설명을 적으면 된다. (급조하느라 아주 말도 안 되는 이상한 메소드이다.)
@param에는 매개변수에 대한 설명을, @return에는 반환값에 대한 설명을, @throws에는 던지는 예외에 대한 설명을 적는다.

주석을 다 달았으면 이제 문서를 생성하면 된다.
Tools에 Generate JavaDoc을 클릭한다.

그리고 한글 깨짐 방지를 위해 Other command line arguments에

-encoding UTF-8 -charset UTF-8 -docencoding UTF-8

을 입력한다.

그리고 OK를 누른다.

그러면

이렇게 생성이 되는 것을 볼 수 있다.

아까 Open generated documentation in browser에 체크를 했기 때문에 문서가 바로 웹 브라우저로 열릴 것이다.
만약 열리지 않는다면 아까 지정해준 경로에서 index.html을 열면 된다.

자바 공식 문서와 똑같이 생겨서 굉장히 그럴듯해보인다.

문서를 만드는 또 다른 방법이 있다.
build.gradle에

javadoc { 
    source = sourceSets.main.java.srcDirs 
    options.encoding = 'UTF-8' 
}

다음과 같은 코드를 적어준다.

그러고 나서 터미널을 열어준다.

경로가 해당 프로젝트 디렉터리인지 꼭 확인한다.
여기에서

이렇게 입력하고 엔터를 치면

성공적으로 문서가 만들어진다.

만들어진 문서는 build 폴더의 docs 안에 javadoc 안에 있다.

그런데 이렇게 문서를 만들고 나서 보니 lombok(롬복)의 @Getter, @Setter, @ToString, @NoArgsConstructor, @AllArgsConstructor 등으로 만들어진 메소드는 문서에 나타나지 않는 것을 알 수 있을 것이다.

이는 delombok을 이용하여 간단히 해결할 수 있다.
build.gradle에 다음과 같은 코드를 추가한다. 아까 build.gradle에 javadoc 부분을 추가했었다면 그 부분을 아래와 같이 변경한다.

javadoc {
    dependsOn delombok 
    source = file("$buildDir/delombok") 
    options.encoding = 'UTF-8' 
    failOnError = false 
}

그러고 나서

을 하면 된다.