[컴][자바] 간단한 javadoc 사용법

javadoc 예시

/**
*
* 여기에 간단한 설명을 적는다. 이부분은 함수 list 에도 간략 하게 들어가게 된다.
*
* 위의 설명에 이어서 좀 더 자세한 이야기를 적는다.
*
* 
* @t.url /test/url
*
* <p><em>Return Field 설명</em></p>
* <ul>
* <li>data : <i>ref.data</i> 참조</li>
* </ul>
*
*
* <p><em>Example</em></p>
* <pre><code>
* "data": {
*     "test" : 10
* }
* </code></pre>
*
* @param id      나의 id
* @param sDate       조회하고 싶은 시작 날짜(date format : yyyyMMddHHmm)
*/
@RequestMapping(value = "/test/url")
public void test(...)

제목을 위해 <b> tag 를 사용하면 될 듯 하다. <h5> 도 가능하지만, parameter 부분의 기본 세팅은 그냥 bold 로 표시되기 때문에 <b> 가 나은 듯 하다.

h5 로 사용하는 것이 가장 적절할 듯 하다. 아래 parameter 와 좀 다른 느낌을 줄 수 있지만 괜찮을 듯 하다.

custom tag 사용

그보다 더 나은 것은 custom tag 를 이용하는 방법이다.(javadoc 1.4 이후에 추가 되었다고 한다.) 그러면 parameter 와 같은 level 로 만들어진다. custom tag 는 아래처럼 javadoc 에 옵션으로 주면 된다.

"c:\Program Files\Java\jdk1.8.0_45\bin\javadoc.exe" -encoding UTF-8 -charset UTF-8 -docencoding UTF-8 -tag t.url:a:"URL : " MyClass.java

"c:\Program Files\Java\jdk1.7.0_25\bin\javadoc.exe" -encoding UTF-8 -charset UTF-8 -docencoding UTF-8 -tag t.returnField:a:"Return Fields:" -tag t.url:a:Url: CdnNewStatsController.java

tag 순서

그러면 parameter 다음으로 설명이 붙는다. 이 tag 의 순서에 대해서는 ref.2 에도 나와 있는데, 위의 option 에서는 먼저 기술된 것이 doc 에서 먼저 나오게 된다.


-tag 에 대한 자세한 설명은 ref. 2 를 참고하도록 하자.

<h6>

custom tag 로 제목에 해당하는 녀석을 만들었지만, 그 안에서 또 소제목을 써야 할 경우도 있을 것이다. 그 때 <h6> 가 가장 적당해 보인다. <h5> 와 custom tag 의 size 가 비슷하기 때문에 크기상으로 가장 잘 맞는 듯 하다.

UTF-8 으로 javadoc 실행

"c:\Program Files\Java\jdk1.8.0_45\bin\javadoc.exe" -encoding UTF-8 -charset UTF-8 -docencoding UTF-8 MyClass.java

.bat

개인적으로 @argfile 등을 이용해서 javadoc 의 option 을 만는든 것보단, .bat 를 만들어서 추가하는 것이 낫다고 편하다고 생각한다. 물론 .bat 에서 @argfile 을 사용하면 더 나은 구조가 될지도 모르겠다.

set encoding=-encoding UTF-8 -charset UTF-8 -docencoding UTF-8
set tags=-tag t.returnFields:a:"Return Fields:" -tag t.url:a:"Url:"
"c:\Program Files\Java\jdk1.7.0_25\bin\javadoc.exe"  %encoding% %tags% MyClass.java

@argfile 에서 tag 에 " 를 사용할 수 없다.

@argfile 을 이용해서 아래 처럼 command 를 수정할 수 있다.

"c:\Program Files\Java\jdk1.7.0_25\bin\javadoc.exe"  %encoding% @tags MyClass.java

tags

-tag t.returnFields:a:Return_Fields:
-tag t.returnExample:a:ReturnExample:
-tag t.url:a:Url:

그런데 여기서 문제는 -tag 에 " 를 이용해서 space 를 넣을 수 없다는 점이다. ref. 3에 같은 문제에 대한 글이 있는데, 해결책은 마땅히 없는 듯 하다. 그래서 결론적으로 @argfile 을 이용하면 space 가 있는 글을 tag 의 string(header) 로 할 수 없다.

ScreenShot

See Also

1. How to Write Doc Comments for the Javadoc Tool

Reference

1. java - How to create custom javadoc tags - Stack Overflow
2. javadoc-The Java API Documentation Generator
3. javadoc arg file -tag name:a:"label" does not work - Javadoc Tool