JavaDoc 작성 방법 및 IntelliJ에서 생성하기 + 모든 주석 한 번에 제거하기

JavaDoc 예시. ( 오라클 Java Se 1.8 )
docs.oracle.com/javase/8/docs/api/index.html

https://docs.oracle.com/javase/8/docs/api/index.html

 

위와 같은 형태의 html 문서를 JavaDoc이라고 한다.
.java 파일에 클래스, 필드, 메소드 등에 JavaDoc 형식에 맞춰 주석을 작성한 다음,
IDE의 기능을 이용해 간편하게 JavaDoc을 생성할 수 있다.

---

필요성

소스 코드 내에 주석을 다는 방식을 이용할 수도 있지만
이 경우 소스 코드를 결국 눈으로 하나하나 다 찾아들어가야 한다.
숲을 한 번에 보진 못하고 나무 하나 하나에 설명을 붙여놓은 느낌이랄까..

반면 JavaDoc 방식을 이용할 경우 전체 프로젝트 구조를 문서화 하여 Overview에 유리할 수 있다.
숲 전체의 지도를 그려서 이 구역에는 어떤 나무들이 있다 이렇게 한번에 파악할 수 있다.
인수인계가 일어날 경우 아주 강력하게 유용할 수 있다.

뿐만 아니라 IDE를 이용할 경우
해당 클래스나 메소드를 사용하려 할 때에, 이에 대한 설명이 자동으로 따라와 보여지므로
직접 코딩을 하는 경우에도 이전 주석 작성자의 도움을 받으며 코딩을 진행할 수 있다.

---

작성 방법

여러줄 주석에 사용하는 /* */ 에서
시작시 *를 하나 추가해서 /** */ 로 작성하면 된다.
IntelliJ의 경우, 이미 작성 완료되어 있는 클래스나 메소드 위에 /** 를 입력하고 Enter를 누르면
알아서 필요한 param, return 등의 태그를 생성해준다.

아래는 코드 예시다.

/**
 * JavaDoc 작성 예시 클래스입니다.
 *
 * @author 작성자명을 입력하는 곳입니다.
 * @version 버전정보를 명시하는 곳입니다.
 * @see Example#printName(String) 
 *
 */
public class Example {
 
    /**
     * 필드값에 대한 설명입니다.
     */
    private String myName = "Java";
 
    /**
     * 이름을 인자로 받아서 콘솔에 출력하는 메소드입니다.
     * 첫번째 줄의 설명만 Method Summary에 나오고 그 이후는 Method Detail에 나옵니다.
     *
     * @param name 콘솔에 출력하기 위해 필요한 String 타입의 이름입니다.
     * @see Example
     * @return 메소드 정상 수행 성공 시 true, 그 외엔 false를 반환합니다.
     */
    public boolean printName(String name) {
        boolean result = true;
        try {
            System.out.println(name);
        }catch (Exception e) {
            result = false;
        }
        return result;
    }
 
}
 

위처럼 작성하고 나면 다른 곳에서 해당 클래스나 메소드를 사용할 때
설명이 연동되어 확인된다.

JavaDoc 방식으로 작성한 주석이 나온 모습

 

@author	작성자를 명시한다
@see	함께 참조할 다른 메소드나 클래스 등
@version	버전 정보를 명시한다
@param	생성자 혹은 메소드가 받는 파라메타를 설명한다
@return	반환값에 대해 설명한다

가장 많이 쓰이는 태그들이다. see태그에서 클래스는 .으로 순차적으로 접근하고, 메소드는 #으로 접근한다.

---

JavaDoc 출력

IntelliJ 기준이다.
Double Shift -> generate JavaDoc -> 옵션 선택 -> Ok 로 간단히 완료다.

세부 옵션을 보자면

어떤 클래스들을 JavaDoc에 포함시킬지가 첫번째다.
Custom scope를 생성해서 포함할 파일을 Include하고 제외할 것을 Exclude한다.
파일이 저장될 경로를 설정하고, 접근제한자를 어디까지 포함시킬지 선택한다.
그 다음은 취향대로 하되, 중요한건 다음 내용을 Other command line arguments 에 추가해야 한다.

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

그러지 않으면 인코딩 에러가 발생한다. OK 누르면 생성이 되면서 생성한 파일을 연다.

 

 

만들다보니 품이 좀 들긴 하는데 너무 꿀잼이다.
앞으로 내가 새로 작성하게될 java 코드들은 모두 JavaDoc까지 완료하도록 해봐야겠다.

 

---

2021.01.05 추가

현재 혹은 선택한 요소의 JavaDoc 제거하기 - Shift + Alt + Z
현재 클래스의 모든 JavaDoc 제거하기 - Shift + Ctrl + Alt + Z
단축키를 사용해보자!

 

Double Shift -> Plugins -> JavaDoc 검색 (안나오면 파란색 Marketplace에서 검색 클릭) -> 설치

github.com/setial/intellij-javadocs/wiki

setial/intellij-javadocs

 

• Remove javadocs on current/selected element: "shift + alt + Z"
• Remove javadocs on all elements of current class: "shift + ctrl + alt + Z"
• From project view available new option to Create javadocs for selected folder/files
• From project view available new option to Remove javadocs for selected folder/files