Flex 프로젝트 문서화 – ASDoc 사용하기

<펌> : http://blog.jidolstar.com/79

Flex 프로그램을 하다보면 내가 만든 프로그램을 문서화를 하고 싶은 경우가 있다. Java의 경우 JavaDoc이라는 아주 좋은 문서생성 프로그램이 있고 Eclipse내에서 Export시 JavaDoc을 쉽게 사용할 수 있으므로 아주 편리하다.

ASDoc은 JavaDoc과 같이 Flex로 만든 프로젝트 안에 .as/.mxml 파일을 .html API 문서 생성해주는 프로그램이다. Flex SDK 2에 보면 이 ASDoc.exe이 있다. 아쉽게도 Flex Builder의 경우 Eclipse처럼 쉽게 문서를 만들지 못하지만 그래도 문서화 시킬 수 있다는게 얼마나 좋은가?

ASDoc을 가지고 간단하게 Flex 문서화 해보자.


1. ASDoc은 어디에 있나?



ASDoc은 Flex를 설치한 폴더안에 Flex SDK 2/bin 폴더에 있다. 이것을 실행하기 위해서는 Command창을 띄워 그 폴더로 이동해야한다.


2. ASDoc을 수행하기 위한 작업



Flex Builder에서 새 프로젝트(ASDocExample)를 만들고 com.jidolstar.core package 폴더를 만들어 그 안에 ExMath.as와 Const.as를 만들었다.


사용자 삽입 이미지

Java와 같은 방법으로 Flex에서도 비슷하게 주석을 넣어주면 된다. JavaDoc처럼 풍부하게 지원해주지는 않는다. 사용하는 방법은 아래 사이트를 참고한다.


위 사이트를 참고하여 아래 내용과 같처럼 주석을 만들었다.
나중에 확인해보면 알겠지만 JavaDoc에서 사용하는 @author , @since 같은 것은 ASDoc에서 해석하지 않는 것 같았다.

Const.as

사용자 삽입 이미지

ExMath.as

사용자 삽입 이미지



3. ASDoc을 이용해 문서화 하자!

윈도우에서 시작>실행을 선택한뒤 cmd를 입력하면 Command창이 뜬다.
거기서 아래 명령을 통해 ASDoc 있는 곳으로 찾아간다.

   cd C:\Program Files\Adobe\Flex Builder 2\Flex SDK 2\bin

여기서 asdoc 명령을 수행할 수 있다. 이 프로그램을 실행할려면 몇가지 옵션을 설정해야한다.


  • -source-path : 프로그램이 있는 경로를 입력한다. 즉, 프로젝트 폴더(E:\…\ASDocExample)를 입력하면 된다.
  • -output : 문서가 저장되는 폴더를 지정한다.
  • -window-title : 브라우져상에 title에 들어가는 문자열이다.
  • -main-title : 문서내에 title이다.
  • -doc-classes : -source-path에서 지정한 프로젝트 폴더내에 문서화할 폴더를 지정하면 된다. 전부 다하고 싶다면 프로젝트 폴더만 입력하면 된다.

옵션설정에 대해서 대충 알았으니 이제 아래와 같이 asdoc을 실행해서 실제로 문서를 만들어보자.

asdoc -source-path E:\…\ASDocExample -output asdoc-output\ASDocExample -window-title “ASDoc Example Documentation” -main-title “ASDoc Example Documentation” -doc-classes ASDocExample

-output을 asdoc-output\ASDocExample로 했기 때문에 그 폴더로 찾아가면 문서들이 만들어져 있는 것을 확인할 수 있다. 거기서 index.html 을 눌러보면 아래와 같은 화면이 나온다.

사용자 삽입 이미지

사용자 삽입 이미지




4. ASDoc 사용시 주의사항

ASDoc을 사용할 때 안되는 경우가 있는데 아래 주의사항만 지킨다면 ASDoc을 무난히 사용할 수 있을것이다.


  1. 명령어 수행중 한글은 사용하지 말자.
  2. 폴더명도 한글이면 안된다. 만약 프로젝트가 있는 경로에 한글폴더가 있다면 프로젝트를 영문 경로만 있는 곳으로 복사한 다음 ASDoc을 사용한다.


5. 정리하며


이로써 ASDoc을 이용해 Flex 프로그램을 문서화 할 수 있게 되었다. ASDoc을 사용하면 주석을 다는데 신중해지고 소스관리할때도 편리하다. 자주 애용해야겠다.

지금까지 Flex 2.0.1 환경에서 작업을 했다.


글쓴이 : 지돌스타(http://blog.jidolstar.com)

(주)리화이트 대표 / CEO & Founder

Next ArticleUsing the TransitionManager Class in AS3