Eclipse에서 Javadoc Export 시 한글 인코딩 오류 해결 방법
Eclipse에서 Javadoc을 생성하려고 할 때 소스 코드에 포함된 한글 때문에 오류가 발생하는 경우가 있습니다. 대부분은 Javadoc 생성 과정에서 소스 파일의 인코딩을 올바르게 인식하지 못해 발생하는 문제입니다. 이번 글에서는 Eclipse에서 Javadoc Export 시 발생하는 한글 인코딩 오류를 해결하는 방법을 정리해 보겠습니다.
1. Javadoc 생성 시 인코딩 옵션 지정하기
가장 많이 사용하는 방법으로, Javadoc 생성 옵션에 인코딩 정보를 직접 지정하는 것입니다.
- Project → Generate Javadoc 또는 Export → Java → Javadoc 선택
- Extra Javadoc Options 항목에 아래 옵션 추가
-encoding UTF-8 -charset UTF-8 -docencoding UTF-8
각 옵션의 의미는 다음과 같습니다.
- -encoding : 소스 파일을 읽을 때 사용할 인코딩
- -charset : 생성되는 HTML 문서의 문자셋
- -docencoding : 생성되는 문서 파일의 인코딩
2. 프로젝트 인코딩 확인하기
프로젝트 자체가 UTF-8이 아닌 다른 인코딩으로 설정되어 있다면 Javadoc 생성 시 문제가 발생할 수 있습니다.
확인 경로
프로젝트 우클릭
└ Properties
└ Resource
└ Text file encoding
가능하면 UTF-8로 설정하는 것을 권장합니다.
3. Eclipse 워크스페이스 인코딩 확인하기
프로젝트가 워크스페이스 설정을 따르는 경우 워크스페이스 인코딩도 확인해야 합니다.
Window
└ Preferences
└ General
└ Workspace
└ Text file encoding
여기 역시 UTF-8로 설정되어 있는지 확인합니다.
4. JDK 환경에서 직접 확인하기
Eclipse 설정 문제인지, 실제 소스 파일 문제인지 구분하기 위해 명령행에서 직접 Javadoc을 생성해 볼 수 있습니다.
javadoc -encoding UTF-8 -charset UTF-8 -docencoding UTF-8 *.java
명령행에서는 정상적으로 생성되는데 Eclipse에서만 실패한다면 Eclipse 설정 문제일 가능성이 높습니다.
5. 자주 발생하는 오류 사례
Case 1. UTF-8로 읽는데 실제 파일은 MS949인 경우
unmappable character for encoding UTF8
실제 소스 파일은 MS949(EUC-KR)인데 Javadoc이 UTF-8로 읽고 있는 상황입니다.
-encoding MS949
옵션을 적용하거나 소스 파일을 UTF-8로 변환해야 합니다.
Case 2. MS949로 읽는데 실제 파일은 UTF-8인 경우
unmappable character for encoding MS949
소스 파일은 UTF-8인데 Javadoc이 MS949로 읽고 있는 상황입니다.
-encoding UTF-8
옵션을 변경하여 해결할 수 있습니다.
정리
Eclipse에서 Javadoc 생성 시 한글 인코딩 오류가 발생한다면 다음 순서로 확인해 보세요.
- Javadoc 옵션에
-encoding,-charset,-docencoding지정 - 프로젝트 인코딩 확인
- 워크스페이스 인코딩 확인
- JDK 명령행에서 직접 Javadoc 생성 테스트
- 실제 소스 파일 인코딩(UTF-8 / MS949) 확인
대부분의 경우 UTF-8로 통일하고 아래 옵션을 지정하면 문제를 해결할 수 있습니다.
-encoding UTF-8 -charset UTF-8 -docencoding UTF-8
