Javadoc 생성하기

이전 글에서는 Javadoc에 대해서 정리했습니다. 이번에는 Javadoc 생성에 대해 정리해보겠습니다.

 

우선 간단한 코드부터 작성해보겠습니다.

예시 프로젝트를 생성하고 package-info.java에 패키지에 대한 문서화 주석을 작성했습니다.

 

다음 SomeClass에 코드를 작성합니다.

package javadoc_test;

/**
 * 예시용으로 만든 클래스.
 *
 * 예시입니다.
 */
public class SomeClass {
    /**
     * 영문자를 소문자로 반환한다.
     *
     * @param word - 소문자로 변환할 문자
     * @return 인자로 들어온 word를 소문자로 반환
     */
    public String toLowerCase(String word) {
        return word.toLowerCase();
    }
}

 

여기까지 Javadoc으로 만들 코드들을 준비했습니다.

 

아래에서는 Javadoc을 만드는 2가지 방법

• cmd 에서 javadoc command를 사용해서 문서 만들기
• IntelliJ에서 지원하는 Javadoc UI를 사용해서 문서 만들기

두 가지 방법을 설명드리겠습니다.

---

CMD 에서 javadoc command 사용해서 문서 생성

먼저 cmd에서 명령어를 사용해 javadoc 문서를 만들겠습니다.

아래의 명령어 양식을 사용합니다.

javadoc  [packages|source-files] [options][@files]

 

• packages : 문서화 하려는 패키지 이름. 하위 패키지도 문서화하려면 -subpackages 옵션을 활용해서 하위 패키지를 지정해줄 수 있다. javadoc 명령어는 기본적으로 현재 디렉터리와 하위 디렉터리에서 지정된 패키지를 찾습니다. -sourcepath를 사용하면 패키지를 찾는 디렉터리 위치를 지정할 수 있습니다.
• source-files : 문서화하려는 java 소스 파일을 지정합니다(Some.java, Class.class 처럼 지정).기본적으로 현재 디렉터리에서 지정된 클래스를 찾습니다.
• options : 다양한 옵션을 지정할 수 있습니다. 각 옵션은 공백(" ")으로 구분됩니다.
• @files : javadoc 명령 옵션 목록, 패키지 이름 및 원본 파일 이름을 순서에 상관없이 포함하는 파일 이름입니다.

위에서 작성한 SomeClass.java 파일의 경로는 다음과 같다고 하겠습니다.

/javadoc-learn/src/main/java/javadoc_test/SomeClass.java

 

먼저 베이스가 되는 패키지를 지정하여 하위패키지까지 전부 Javadoc 문서를 생성하겠습니다.

// 현재 디렉터리를 기준으로 패지키를 지정 (현재 디렉터리에 지정하고싶은 패키지가 있을 때)
javadoc javadoc_test

// 패키지가 있는 경로를 지정하려면 -sourcepath를 사용
javadoc -sourcepath /javadoc-learn/src/java/main javadoc_test

 

다음은 파일 이름을 지정해서 문서화를 하겠습니다.

 

// 파일 이름을 지정. 경로는 현재 디렉터리를 기준으로 하기 때문에 파일앞에 경로를 지정할 수 있다.
javadoc /javadoc-learn/src/main/java/javadoc_test/SomeClass.java

// 와일드 카드('*')도 사용이 가능합니다.
javadoc /javadoc-learn/src/main/java/javadoc_test/*.java
javadoc /javadoc-learn/src/main/java/javadoc_test/Some*.java

 

와일드 카드 사용 시 매칭되는 파일이 하나도 없다면 에러가 발생한다.

 

이렇게 Javadoc문서가 다음과 같이 만들어진다.

 

좀 더 자세한 내용은 오라클의 javadoc command 문서를 참고해주세요.

---

IntelliJ javadoc UI를 활용해서 문서 생성

이제 인텔리제이에서 shift 2번을 연속으로 눌러줍니다.

그럼 아래와 같은 화면이 나옵니다.

 

'generate javadoc' 을 검색해서 실행합니다.

실행하면 아래와 같은 화면이 나옵니다.

원하는 옵션을 선택합니다.

저는 Javadoc 생성하기를 원하는 범위를 SomeClass.java 파일로 지정했고

Output Directory는 Javadoc 이 생성하는 HTML 문서가 저장되는 디렉터리입니다. 원하는 위치로 지정해줍니다.

Other command line arguments 에는 옵션을 지정해줄 수 있습니다. 여기서는 한글이 깨지지 않게 하려고 인코딩을 UTF-8 로 지정했습니다.

 

여기까지 하고 실행하면 Javadoc HTML이 만들어지고 실행됩니다.

아래는 생성된 HTML 문서입니다.

 

패키지 문서화 주석과 클래스와 메서드에 적용한 문서화 주석이 모두 잘 적용된 것을 볼 수 있습니다 :)