'javadoc'에 해당되는 글 1건

  1. 2011.03.28 문서화 - 1. JavaDoc
2011.03.28 22:41
 요즘 개발 환경 만들기에 눈이 간다. 단순히 Text Editor에 도움을 주는 plug-in 뿐만 아니라  Bug tracker, JUnit, 위키, Git, Maven, Ant 등등 개발하는데 쓰고 싶은 것들이 너무 많아서 오히려 스트레스가 될지경이다 -..-

 하지만 오늘은 지금과는 조금 다른 성격의 툴인 JavaDoc에 대해서 다루어 볼까한다.

 위에서 말한 것들은 다른방식으로 하고 있는 일들을 더 편하게, 실수 없게 할 수 있게 만들어 주는것들 이지만 문서화 및 주석 달기는 조금 다르다.

 정작 Product와는 별 상관 없어 보이기도 하고 귀찮아서, 또는 개발 일정에 쫒겨서 모든 개발자들이 필요성을 느끼지만 잘 안되는 부분 중에 하나 일 것이다.

  필자 또한 만들어 놓은 소스코드를 3일만 지나서 다시 봐도 무엇을 해놓은 코드인지 모를때가 많다. 

  어느 책에서나 볼 수 있는 서론은 여기까지 하고 본론으로 들어가보자.
 
  오늘 사용해볼 툴은 JavaDoc인데  Eclipse Java IDE에 Built-in 되어있고, 사용법도 매우 간단하여 주석만 달면 자동으로 Document를 만들어 준다.

 Sun Java의 공식 API문서와 같은 훌륭한 문서를 주석 달기 만으로 만들수 있다니 매우 훌륭하지 않은가? 더욱이 기본 IDE에 built in 되어있다는 장점은 개발환경을 바꿀때마다 반복되는 작업환경 구성의 사용자 수고까지 덜어준 셈이다. 최고의 튜닝은 순정아니겠는가. 기본 탑재된 툴을 유용하게 써보자.




기본적인 주석의 형태는 다음과 같다.

/**
   * @author
   * @param 
   * @return
   */


 클래스나 메소드 위에서 /**을 입력하고 엔터를 치면 이클립스가 자동으로 아래의 내용에서 인자 또는 리턴이 있는지를 보고 입력해준다.

 위와 같이 간단한 코드를 하나 작성해보자.



이제 JavaDoc으로 만들어보자.

Eclipse 메뉴의 Project -> Generate JavaDoc을 누르고 Javadoc command에 현재 JDK의 bin안의 javadoc.exe를 설정해주고 Javadoc으로 만들 프로젝트를 선택하고 Next를 눌러보자.

 이제 만들어진 JavaDoc을 보자. 


 폴더를 변경하지 않았다면 프로젝트 폴더에 doc 폴더안에 위치할 것이다.
 index.html을 열어보면 다음과 같은 익숙한 Layout의 html을 볼 수 있을 것이다.

 참고로 주석 내부에 자주 쓰이는 annotation은 다음과 같다.

  {@link} - 링크를 걸때 사용

  @deprecated - 쓰기를 추천하지 않는 클래스 또는 메소드
  @see - See alos로 클래스 또는 메소드의 링크 표시
  @version - 버젼
  @serial - serializeable한 클래스
  @exception - 발생가능한 exception


 기본적인 기능을 익혔으니 쓰기 쉽게 Code Template를 만들어보자.
 만드는 방법은 window > Preferences > Java > Code Style > Code Templates 에서 내용을 수정하면 된다.

우선 Comments의 Types을 다음과 같이 수정해보자.

/**

 * @author ${user}

 *

 ****************************

 *     코드 수정 히스토리

 *  날짜          작업자         태그

 *${date}  ${user}  ${tags}

 ****************************

 */


그리고 Code의 New Java Files를 다음과 같이 수정하자.

/*

 * 작성일 : ${date}

 * 작성자 : ${user}

 *

 * 설명

 */


${filecomment}

${package_declaration}


${typecomment}

${type_declaration}


그리고 하단부에 Automatically add comments for new methods and types를 체크하자.

이제 새로운 자바 파일을 만들어보자.



상단에는 작성일, 작성자의 추가정보가, 클래스 시작부분에는 코드 수정히스토리가 자동으로 적용되어 있을 것이다.

 하지만 이는 새로 만든 문서이고, 만들어놓은 문서를 이와 같은 포맷으로 변경하는 방법은 없을까?

 
 이미 만든 Java File이므로 New Java Files의 Template는 적용할 수 없는 것 같았다.(필자가 잘못 알고 있을수도 있다.)
 하지만 Comment에서 적용한 template는 alt+shift+j(Source > Generate element comment)를 실행하면 적용이 된다.






 오늘은 Java Code에서의 문서화를 도와주는 JavaDoc에 대해서 알아 보았다.

 다음 포스팅은 한단계 더 나가서 XML 방식으로 일반화된 문서를 만들어주는 툴인 Apache Forrest를 다루어 볼까 한다.
 Forrest는 Apache 자카르타 프로젝트의 일환으로 다른 프로젝트의 문서화에도 쓰이고 있으며, XML Framework기반이며 HTML, PDF 등 많이 사용하는 문서로도 만들어주고, Ant, wiki등과의 연계도 매우 잘 되어있는 툴이다. 




추가 : 한글깨짐이 일어난다면 Generate javadoc을 할 때 첫번째 메뉴에서 javadoc.exe 뒤에 -locale ko_KR -encoding UTF-8 -charset UTF-8 -docencoding UTF-8 또는 마지막 메뉴에서  -encoding UTF-8 혹은 -encoding EUC-KR 인코딩 옵션을 추가하면 된다.
신고
Posted by JAVA_HOME

댓글을 달아 주세요


티스토리 툴바