Posts Tagged ‘javadoc’
hudson – javadoc 생성하기
사실, 개발하면서 주석을 다는 것은 무척이나 흥미로운 귀찮은 일이다.
게다가 포맷을 지키고, 어떤 파라미터가 넘겨지고, 리턴 값은 어떻고,
어떤 상황에서 어떤 exception이 던져진다는 것까지 써야 한다면 더더욱 그렇다.
보통 프로그램부터 작성한 후, 주석을 달라고 한다면,
주석을 다는 것이 아주 하기 싫은 일이 될 가능성이 크다고 생각한다.
주석을 달면서, 코드 리뷰도 하고, 분석도 하고, 수정도 하는 선순환이 되기 보다는
상당히 형식적인 주석 작업이 될 확률이 더 높아진다.
오히려, 보다 양질의 주석을 달기에 좋은 시기는 해당 부분을 프로그램화 할 때라고 생각한다.
모든 프로젝트를 완료한 후, javadoc을 사용하는 대신에
초기부터 javadoc을 사용해 보자.
자신이 작성하는 코드와 비슷한 시기에 산출물을 생성하는 것이다.
생성된 산출물을 확인하여, 편집하는 수고를 나중으로 미루지 말자.
다행히, hudson에서는 기본적으로 javadoc을 publish하는 기능이 내장되어 있다.
Hudson의 설정 변경하기
프로젝트의 configure 메뉴를 선택한다.
Post-build Actions에 보면, 별도의 플러그인을 설치하지 않아도 javadoc에 대한 옵션을 설정할 수 있도록
되어 있다.
Publish Javadoc 옵션을 체크하면, javadoc 문서의 위치를 지정할 수 있다.
프로젝트명/docs/javadoc 과 같이 적어준다.
(본인의 경우, 프로젝트명/docs/javadoc에 javadoc 문서가 생성되도록 설정해 두었다.)
ant task 추가하기
javadoc의 디렉토리를 다음과 같이 선언하고,
<!-- javadoc directory -->
<property name="javadoc.home" value="${basedir}/docs/javadoc" />
javadoc의 task를 다음과 같이 선언한다.
<!-- target : javadoc -->
<target name="javadoc">
<javadoc sourcepath="${src.home}" windowtitle="J's project"
destdir="${javadoc.home}" encoding="UTF-8" charset="UTF-8"
docencoding="UTF-8">
</javadoc>
</target>
이제, javadoc의 task까지 준비하였다.
ant task로서의 javadoc을 호출하기만 하면 될 것이다.
ant task 실행 설정하기
이제, configure에 Build에 보면, 지난 번에 설정한 all.emma.report task가 보일 것이다.
그 밑에 새로운 ant task를 추가하자.
위의 설정으로부터, 새로운 ant task는 javadoc이라고 이름을 붙였다.
(일부러, all.emma.report에서 compile을 하도록 했으므로, 위의 ant task 작성시 depends를 설정하지 않았다.)
설정을 저장하고 나면, hudson 좌측 메뉴에 javadoc 메뉴가 나타날 것이다.
Build Now 를 클릭하거나, 자동으로 빌드가 된 후에 javadoc 생성 여부를 확인해보자.
이로써, hudson에서 javadoc을 생성하고 publsih해 보았다.
이제, 개발하면서 자신의 프로젝트가 빌드되면서 생성되는 산출물의 결과도 함께 확인하며,
문서 작성도 함께 해보자.
javadoc과 package.html
작성한 자바코드를 표준 doclet의 javadoc으로 돌리면,
package의 설명이 휑허니 빈칸으로 나온다.
어떻게 주석을 달면, package에 대한 설명을 넣을 수 있을까?
package의 entry에 package.html을 작성해 주면 이 문제가 해결된다.
만약 package ab.cd.ef.* 가 존재한다면,
디렉토리가 ab/cd/ef가 존재할 것이다.
따라서, ab/cd/ef/pacakge.html을 작성해주면 javadoc 실행시
package의 description을 채워준다.
이 때, 작성 형식은 매우 간단하다. 다음과 같이 기록하기만 하면
body 부분의 설명이 그대로 반영된다.
<head>
<body>
넣고 싶은 설명 기록
</body>
</head>
</html>
Eclipse에서 javadoc을 pdf로 출력하기
LaTex를 쓰는 방법은 LaTex의 특성상 가독성이 좋은 결과물을 만들 것으로 기대되나,
별도로 변환을 한번 더 해줘야 하는 번거로움이 있으므로 이왕이면 손이 덜 가는 방법을 찾아보게 되었다.
www.doclet.com에 소개된 library 중 하나인,
AurigaDoclet(http://aurigadoclet.sourceforge.net/)을 사용해 보자.
사용법은 간단하다.
ANT에서 지정할 수 있는 설정은,
<javadoc packagenames=”package-names”
sourcepath=”source-path”
doclet=”com.aurigalogic.doclet.core.Doclet”
docletpath=”aurigadoclet-path”
additionalparam=”options”
>
<classpath refid=”aurigadoclet.class.path” />
</javadoc>
package-names package names source-path path of the java source files aurigadoclet-path path to the AurigaDoclet.jar file in AurigaDoclet’s bin directory options AurigaDoclet options.
이며, 이 때 사용할 수 있는 옵션으로
-format
- The output format.
Supported values: fo,pdf,ps,pcl,svg.
- -out
- Output file path.
- -notoc
- Do not generate TOC page.
- -nonavigation
- Do not generate navigation tree.
- -nolinks
- Do not use hyperlinks.
- -noindex
- Do not generate a keyword index.
- -leftmargin
- Left margin in points. Default is 30.
- -rightmargin
- Right margin in points. Default is 30.
- -topmargin
- Top margin in points. Default is 10.
- -bottommargin
- Bottom margin in points. Default is 10.
- -headertext
- XHTML text to be used as page header.
- -headerfile
- XHTML file to be used as page header.
- -footertext
- XHTML text to be used as page footer.
- -footerfile
- XHTML file to be used as page footer.
- -headerheight
- Height of page headers in points. Default is 50.
- -footerheight
- Height of page footer in points. Default is 20.
- -coverfile
- XHTML file to be used a cover page.
- -cssfile
- CSS file to used for formatting the output.
Default css file is located in src/com/aurigalogic/doclet/resources/default.css
- -xslfile
- Custom xsl file to be used for formatting the output.
가 있다.
따라서, Eclipse에서 이 정보를 활용하여, aurigadoclet을 사용하도록 환경설정하고
실행시 옵션으로 위의 옵션을 택하여 지정하면 된다.
1. Eclipse의 해당 프로젝트로부터, Export > JavaDoc > Use custom doclet 선택
2. Docletname에 com.aurigalogic.doclet.core.Doclet 을
3. Doclet class path에 설치한디렉토리binAurigaDoclet.jar 를 써준다.
Next를 누른다.
4. Extra Javadoc options에
-format pdf -out “만들 pdf의 경로와 이름” 을 적어주고,
Finish 누르면 pdf가 생성된다.
everydayminder 