[Javadoc] error: bad use of '>' 오류에 관하여 - @code 사용법

Javadoc 오류가 발생 !

Open source에 특정 기능을 구현하고 있었습니다. 특정 기능을 구현하고, 메서드 설명(javadoc)에 아래 예시처럼 작성을 완료하였습니다.

/**
* ~
* ~
* ~ when maxQueueSize > 0
* ~
* ~
*/
public void specificMethod(int maxQueueSize) {
	...
}

기능 테스트 상 이상은 없었으나 build시 제목과 같은 `error: bad use of '>'` javadoc 에러가 발생했습니다.

 

javadoc은 사실 많이 작성해보지 않은 터라, 이런 에러에 대해서도 당황했고, "'>' 문자가 잘못된 사용이라는 건가?", "왜?"라는 의문이 먼저 들었습니다. 그러다보니 '>' 사용 에러가 아닌 다른 오류겠지 하며 stacktrace를 확인했는데 다른 오류는 없다는 것을 알게 되었습니다.

 

 

 

그럼 '>'를 javadoc에서 사용하는 것이 왜 잘못된 것일까?

정답을 먼저 말씀드리자면, '>'를 사용하는 것이 잘못된 것은 아니고 단순히 Plain text로 '>'만 사용하는 것이 잘못된 사용법인 것입니다.

이러한 빌드오류를 막기 위해. 즉, '>'의 올바른 사용법은 '{@code ... > ...}' 처럼 @code Javadoc tag를 사용하면 됩니다.

 

예를 들어, 위 예제를 올바른 사용법으로 바꿔보면 다음과 같습니다.

/**
* ~
* ~
* ~ when {@code maxQueueSize > 0}
* ~
* ~
*/
public void specificMethod(int maxQueueSize) {
	...
}

당연히도 '<' 문자 또한 위와 같이 @code Javadoc tag를 사용해주어야 합니다.

 

 

정답을 알았으니, 왜 '>', '<' 같은 문자들의 경우 왜 Javadoc tag를 사용해가며 처리를 해주어야하는 것일까?

이유는 사실 단순한데요, HTML/XML tag 및 Java generic 사용 시와 겹치는 문자이기 때문입니다.

 

Javadoc 내부에는 HTML/XML tag가 사용될 수 있고, 그러한 tag 내부에서 Java 코드(code snippet)가 사용될 수 있습니다. 그렇기에 쌍이 아닌 '>', '<' 문자들이 단독으로 사용되면 위 사용법과 혼동이 되어 tag, code 들이 제대로 작성되지 않을 수 있으므로 잘못된 사용법(bad use)으로 규정하고있고 이를 막고 있는 것입니다.

 

 

{@code}  Javadoc tag

문제를 해결해 준 {@code}에 대해서 알아봅시다. {@code} Javadoc tag는 Java 5에 등장했습니다.

 

Javadoc에서 Java 코드(code snippet)을 작성하고 싶은 경우가 많은데, 그런 경우 코드를 그냥 plain text로 적으면 앞서 말한 '<', '>' 문자도 그렇고 코드를 올바르게 표현해주지 못하는 경우가 있습니다. 그렇기에 코드작성에 {@code} tag를 사용하면 앞선 문제들을 해결할 수 있습니다.

 

 

<pre> HTML tag

갑작스럽지만 Javadoc 작성 시 원하는대로 동작하지 않는 경우가 하나가 더 있는데, 바로 줄 바꿈(line breaks)과 들여쓰기(indentation) 입니다. 왠지는 모르겠지만... 줄 바꿈과 들여쓰기가 지원이 되지 않아 빌드했을 때 다 붙어서, 원하지 않는 형태로 작성된 것을 보는 경우가 적지 않았습니다.

 

이런 경우엔 <pre> HTML tag를 사용해 문제를 해결할 수 있습니다.. HTML을 배워 봤으면 아시겠지만 <pre>는 performatted text를 위한 HTML에서 기본으로 지원하는 tag입니다. HTML 렌더링 시 <pre> tag 내에 있는 것은 문자 그대로 표현되어지게 됩니다. 즉, 줄 바꿈과 들여쓰기 또한 유지가 되어 원하는 형태로 작성할 수 있습니다.

 

물론, 앞선 문제처럼 '<', '>'는 <pre> tag 내부에서 사용하더라도 제대로 표시되지 않습니다. <pre> tag 자체가 HTML 태그이고, 내부에 다른 HTML tag가 들어갈 수 있기 때문에 혼동이 될 수 있는 '<'. '>'는 사용할 수 없습니다.

 

 

<pre> , {@code} 같이 사용하기

앞에서 언급하진 않았지만, {@code} 내부에 줄 바꿈과 들여쓰기를 작성하더라도 지원되지 않습니다.

결국엔 '<', '>' 같은 특정 문자들을 다 사용하며 코드 표현을 하고 싶으면서, 줄 바꿈 및 들여쓰기도 사용하고 싶다면 <pre>, {@code} tag를 함께 사용해야합니다.

/**
 * <pre>{@code 
 * public void specificMethod(int maxQueueSize) {
 *
 *   // indentation and line breaks are kept 
 *
 *   List<Integer> someData = null;
 *
 * }</pre>
 */
public void specificMethod(int maxQueueSize) {
	...
}

---

 

위 내용의 대부분은 아래 블로그에서 참조하였습니다. 위 내용들을 요약해놓고 한 눈에 보기 좋은 표들이 정리되어있어서 한 번 보시면 좋을 것 같네요 :)

A Guide to Formatting Code Snippets in Javadoc

 

 

---

이것 외에 전체적인 Javadoc의 작성법을 알고 싶다면 아래 주소를 참고하면 좋을 것 같습니다. (저도 잘 몰라 배워야 하는 부분입니다 😂)

https://www.oracle.com/kr/technical-resources/articles/java/javadoc-tool.html

https://www.baeldung.com/javadoc

https://blog.live2skull.kr/javadoc/java/java-javadoc/