<펌> : 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을 무난히 사용할 수 있을것이다.- 명령어 수행중 한글은 사용하지 말자.
- 폴더명도 한글이면 안된다. 만약 프로젝트가 있는 경로에 한글폴더가 있다면 프로젝트를 영문 경로만 있는 곳으로 복사한 다음 ASDoc을 사용한다.
5. 정리하며
이로써 ASDoc을 이용해 Flex 프로그램을 문서화 할 수 있게 되었다. ASDoc을 사용하면 주석을 다는데 신중해지고 소스관리할때도 편리하다. 자주 애용해야겠다.
지금까지 Flex 2.0.1 환경에서 작업을 했다.
글쓴이 : 지돌스타(http://blog.jidolstar.com)