▶ Friends
ASDoc : Flex SDK 에 포함된 Document 제작툴이죠. 네… 뭐… 컴파일러보다 예민한 소녀 감수성을 가지신 탓인지, terminated 가 드럽게 잘 뜬다는 것만 빼면 나름 좋습니다.
다운로드 : http://www.adobe.com/cfusion/entitlement/index.cfm?e=flex3email
PHPDoc : PHP Document 를 만들어줍니다. 웹상에서 돌아가기도 하기 때문에 유일하게 GUI 가 제대로 지원된다고 볼 수 있을것도 같네요.
다운로드 : http://sourceforge.net/project/showfiles.php?group_id=11194
ScriptDoc(Aptana) : Javascript Document 를 만들어줍니다. Aptana 에 포함이 되어있길래 걍 쓰고 있습니다.
다운로드 : http://www.aptana.com/studio/download
eclipse update 설치 : http://update.aptana.com/install/studio/3.2/
▶ 설치
ASDoc 은 일단 Flex SDK 가 있어야 합니다. Flex builder 안에는 이미 포함이 되어있으므로, Flex builder 를 사용하는 분은 별달리 뭘 설치하실 필요는 없습니다. 그 외에 다른 에디터를 사용하시는 분들이라면 SDK 를 다운로드 받아 놓으시면 됩니다. (폴더 정리는 이쁘게~ 해놓으시면 되구요.)
PHP은 커맨드라인으로도 작동이 되나, 왠만해서 web 상에서 생성하는게 편하겠죠. 다운로드 그냥 받아놓습니다.
ScriptDoc 은… Aptana 를 사용하셔야 하는데…;;; 뭐 javascript 코딩할 일이 없으신 분들이라면, 걍 "이런게 있었구랴~ 홀홀홀~" 하면서 보기만 하세요. Eclipse plug-in 인데 Flex builder 만큼 커다란 녀석이라서, 문서화 테스트 한번 해보겠답시고 설치하기에는 상당히 머시기 합니다.
▶ Ant 를 사용해서 ASDoc 퍼블리싱 하기
일단… ASDoc 은 커맨드라인 툴입니다. 뭐 쉽게 이야기하자면, 도스창에서 돌아가죠. 그런고로 사용하기가 겁내 귀찮습니다. 그래서, Ant 를 사용해서 셋팅을 해놓는게 정신건강에 좋고, 어짜피 Flex builder 든 FDT 든 Ant 가 깔려있고, 사용하지 않은지 오래되서 잘 모르겠지만, FlashDevelop 역시 Ant 를 권장한다고 알고 있으므로, Ant 환경은 대체적으로 갖춰져 있다고 볼 수 있겠네요.
당구장 : 개인적으로 FDT 를 사용하므로 FDT 위주로 진행합니다.
HelloASDoc 이라는 프로젝트를 하나 만들어줍니다.
Sprite 를 상속받아서 ExampleASDoc class 를 하나 만들어주고요.
되먹지 않은 주석을 달아줍니다.
복잡하게 달아도 되는데… 대충 설명과 @param 만 달아도 잘 돌아갑니다. 복잡하게 달아봤자 코딩하기만 번거로워지니 조금만 적는게 좋습니다.
TestASDoc.ant 라는 ant 파일 하나를 만들어줍니다.
그리고, 내용으로는 아래의 내용을 적어줍니다. Ant 태그에 대해서 조금 설명 드리자면…
<property name="A" location="aaa"> 는 AS 로 치면 그냥 public const A:String = "aaa"; 와 비슷합니다. 걍 설정변수로 쓸수 있다고 생각하시면 됩니다. 아래쪽의 내용을 보면, ${ASDocs.dir} 과 같은 것들을 잔뜩 볼수 있는데, 위쪽에 있는 property 와 연결되어 있는걸 확인하실 수 있습니다.
<target name="B"> 는 AS 에서 public function B():void 로 생각하시면 됩니다. 그냥 어떤 동작을 하는 동작단위 입니다.
그리고, 마지막으로 중요한… (뭐 이걸 배껴서 써도 되겄지만…) <exec> 은 특정 exe 프로그램을 동작시켜주는 기능입니다. 커맨드라인 툴들을 <exec> 으로 연결시켜서 사용함으로서 왠만해서 사용하기 짜증나는 (좋아하는 사람들도 더러 있는) 도스창 사용을 하나의 더블클릭 할 수 있는 버튼으로 대체시킬수 있습니다.
뭐 대충봐서도 알겠지만, delete, mkdir, exec… Dos 나 Telnet 명령어들과 닮아있는 것들이 꽤 많습니다.
뭐 하여튼… 위와같이 적어놓습니다.
Ant Task 에서 "Add buildfiles" 버튼을 누르고
조금전 만들어놓은 TestASDoc.ant 파일을 등록시킵니다.
뭐 그러면 대충 이렇게 등록이 되는데요. target 들을 확인할 수 있습니다. 이제 compile target 을 더블클릭 하면…
Console 에 이렇게 뜹니다. 요렇게 안뜨면 에러나서 뻗은겁니다.
뭐 구지 이야기 하자면, 컴파일러가 정상인 이라면, ASDoc 은 상당히 병약한 소녀이미지 입니다. 졸라 잘뻗어요. 왠간히 떡코딩 하다보면 거의 문서 제대로 안나올때 많으니, 안되면 걍 포기하세요… 저처럼 "아 썅! 왜 안돼!" 하면서 집착하다보면 2~3일 우습게 지나가거덩요. 안되면 "안되나 보네… 홀홀홀~" 하면서 살아야지, 괜시리 매달리다보면 피봅니다.
뭐 폴더로 들어가면 아까 설정해 놓은 as3_testDoc 폴더가 만들어져 있는걸 확인할 수 있구요.
index.html 을 눌러보면 문서가 뽑혀나와 있는걸 확인할 수 있습니다.
개인라이브러리를 이런식으로 만들어두면 1초마다 1초만큼 늙어가는 두뇌라도 대충 개발할때 도움이 됩니다. 제가 요새 좀 기억력이 저하되고, 기력도 저하되고, 밥맛도 잘안나서 고기가 없으면 밥이 안넘어가고, 여자친구도 없어서 외롭고… 뭐 하여튼 복합적인 문제 때문에 기억력이 부쩍 떨어져가는지라 ASDoc 으로 만들어서 많이 보고 있습니다.
▶ 소녀감성 ASDoc 달래기
뭐 왠만해서 "포기하면 편해…" 라고 말하고 싶지만, 꼭 만들고 싶습니다! 라고 이야기 하는 몇몇 분들을 위해서 구지 이야기하자면… ASDoc 이 뻗어버리는 대체적인 이유는 라이브러리의 부재때문입니다.
예를들어 script 에 fl package 를 넣으면
뻗습니다.
그리고, 문서도 날라갑니다.
뭐 그나마 이 경우는 에러메세지라도 보여주는데, 왠간한 경우 에러메세지도 없이 걍 뻗어버리곤 합니다. 그럼 사람 미치죠.
이럴땐 이렇게 component swc 경로로 들어가서 특정폴더에 swc 들을 왕창 복사해놓고…
요렇게 Swc.dir 프로퍼티를 하나더 만들고, -library-path <arg> 를 하나더 만들어주면…
젠장… 안되네요… ㅡ ㄴ ㅡ
뭐 하여튼… 만일 caurina tweener 같은것들 때문에 에러가 난다면 이런식으로 해결이 가능합니다. 이 에러 잡으려고 역추적 하다보면 한오백년 걸릴것 같으니깐, 때려치겠습니다. 왠만하면 ASDoc 으로 만들것들은 순수하게 flash package 만 사용하는 녀석으로 하는게 좋습니다. (그런게 될 턱이 없지만…) 아니면, Flex builder 의 library project 를 통해서 필요한 참조라이브러리들을 swc 로 만들어놓은 다음에 연결해서 사용하면 되구요.
소녀감성 ASDoc 달래기 어렵습니다. 뻑하면 뻗어대서 초기 셋팅하느라고 짜증나 죽는줄 알았어요. (뭐 이따우로 만들어뒀는지… 이가 갈린다능…) 뭐 하여튼 뻗어대는데 클라이언트는 문서 달라고 지랄을 해대거나 한다면 이런식으로 달래서 만들면 됩니다.
아… Fla 에 연결된 (예를들어 Linkage class 로서 class 내부에서 this["linkagename"] 과 같은식으로 참조를 하는) class 는 왠만해서 만들다 뻗습니다. flash 의 디자인과 협조작업이 들어가는 class 의 경우 거의 대부분의 경우가 뻗는다고 알아두면 좋습니다. (그래서 개인적으로 문서화를 시킬 클래스패스에는 추상클래스로 기본형태를 만들고, linkage name 으로 연결되는 클래스들은 문서타겟 밖으로 빼서 작업합니다.)
가능한한 Script 로만 구성된 녀석을 Document 로 하세요. (어떻게 될지도 모르겠다는 생각이 들기도 하지만, 그런 방법 찾기전에 혈압올라 쓰러질것 같아서 포기하렵니다…)
▶ PHPDoc 만들기
아… PHPDoc 은 참 착해요… (^ㅡ^b) 일단 코딩을 해볼까요…
HelloPHPDoc 이라는 기본타입 project 를 만들고, ExamplePHPDoc.php 이라는 file 을 만들어 줍니다.
그리고, 대충 코딩을 합니다.
그리고, xampp 를 실행시켜 줍니다. 잘 모르겠는 분은… http://ssen.name/zb/recipe/1983 를 참고하세요. xampp 의 webroot 가 eclipse workspace 로 설정되어 있다는 가정하에 진행하겠습니다.
다운로드 받은 phpDocumentor 를 eclipse workspace 에 복사시켜 둡니다.
그리고, localhost/폴더명으로 접속을 하면… 짠~ 하고 docBuilder 가 나타납니다.
Directory to parse 에 파싱할 폴더를 넣어줍니다.
그리고, Output 에서 스킨을 적절하게 선택하고, 문서가 생성될 폴더를 적어줍니다.
그리고, 하단에 create 버튼을 누르면…
하단 프레임에 뭐라 뭐라… 꽤 길게 뜨는데요.
문서폴더에 들어가보면 문서들이 생성되어 있는것을 확인할 수 있습니다.
index.html 을 눌러보면 정상적으로 출력된 것을 확인할 수 있습니다.
아마 맨처음에는 한글출력이 정상적으로 되지 않을것입니다. 그럴때는 자신이 사용하는 스킨의 경로로 들어간 다음에 tpl 파일들을 연 다음에
이렇게 iso-8859-1 로 캐릭셋이 되어있는 것들을 모두 utf-8 로 바꿔주면 됩니다. 일괄변경등을 통해서 바꿔버리면 됩니다.
그리고, 하단프레임의 주소를 즐겨찾기 등으로 저장해놓으면 다음부터는 이 주소를 통해서 설정을 건너뛰고 바로 바로 문서를 만들수 있습니다. 이 주소를 호출하면 문서가 만들어지는 형식이거든요.
개인적으로는 document root page 에 이런식으로 링크를 걸어둬서 사용하고 있습니다.
▶ JavascriptDoc 만들기
뭐 이건 아까도 말했다시피… Aptana 라는 Ajax 개발툴의 내장기능 입니다. Aptana 의 ScriptDoc 은 기본적인 문서출력 이외에도 독특한 역할을 하는데요.
ScriptDoc 없이 코딩을 하면 이렇게 뜨지만…
ScriptDoc 을 넣어서 코딩을 하면 이렇게 뜹니다.
ScriptDoc 은 동적언어인 Javascript 가 가지는 변수형 부재의 한계성을 극복하는데 도움을 줍니다. 꽤 신선한 발상이지요…
ScriptDoc 역시 별다른 에러없이 무난하게 문서가 뽑혀나오는 편입니다.
대충 코딩을 해본 다음에…
상단에 보이는 Generate HTML Docs 를 누릅니다.
그러면 이렇게 뽑혀나오는걸 볼 수 있습니다.
굉장히 편리하게 뽑혀나오는 대신에… 각 파일이 폴더 하나로 묶이는 안타까운 모습을 보이는 편인데요. 이런것은 php 의 folder 읽기 등을 통해서 대충 프로그램으로 짜면 해결될 문제라고 봅니다. (혹은 AIR 로 만드는것도 괜찮은 방법이겠죠.)
어쨌든 문서는 이런식으로 뽑혀나오게 됩니다. 그닥 편리하지는 않지만, Flash 개발자도, 서버사이드 개발자도, 디자이너도, HTML 코더도 사용하는 javascript 에 대한 문서화 작업은 여러모로 팀 작업에 큰 유연성을 주게 됩니다. 서로 작업공유가 안되서 어리버리 대는걸 지켜보면서 "아이고 화상들아…" 할 일이 적어지는거죠…
파일은 index.html 의 html 완성형과 동시에, index.html.xml 이라는 xml 형도 만들어주기 때문에, 적당한 xslt stylesheet 를 통해서 별도의 양식을 만들거나, 혹은, flash 같은것에서 읽어들여서 문서형태로 만들거나 할 수 있습니다. xml 파일의 제공에 대해서는 꽤 높은 점수를 주고 싶네요.
▶ Interface 구축을 통한 서버사이드 개발자들과의 연계작업
문서화 작업은 라이브러리를 배포할때나 자기 자신의 기억력을 저주할때도 도움이 되지만, 실제 작업시에도 꽤 큰 도움이 되곤 합니다. 가장 상큼하게 작용하는 경우는 Remoting 을 통해서 작업할때인데요… 간단하게 지난번에 소개해드린 Rosa 를 통해 예제를 보여드리자면…
이런식으로 Remoting 에 대한 데이터 인터페이스를 만들어놓고…
이런 문서를 서버사이드 개발자에게 전달할 경우 서버사이드 개발자는…
이런식으로 인터페이스에 근거한 데이터 커넥터의 제작이 가능합니다. 이런 논리는 결국 반대로 생각해서 PHP 에서 인터페이스를 문서화 시켜서 전달했을때 ActionScript 가 그것을 구현한다… 로도 이어질 수 있죠.
개인적으로 ActionScript, PHP, Javascript 를 써서 그렇지, Java, Ruby, Python, C# 등… 왠만한 언어들은 다 문서화 제작도구를 지원합니다. 문서화 제작도구가 없는 언어가 오히려 더 희안할 정도이지요. (그리고, 대체적으로 Document 주석은 표준적인 /** */ 과 @param 등을 그대로 구현합니다.) 간단한 주석작업을 통해서 작업내역을 공유하는 것은 작업의 진행에도 그렇고, 차후에 유지/보수에도 그렇고 많은 도움을 줍니다. 무엇보다 ActionScript 쪽에 만연해 있는 "혼자 하는게 편해용~" 이라는 논리는 대형 시스템 작업이 되면 여지없이 박살이 나기 때문에 (혼자 못만들어요 그딴거… 뒤져요… 아주… 킬미킬미… 소리가 절로 나와요), SVN, ASDoc 등을 통해서 최대한 간편하게 작업을 공유하는 스킬을 가져야만 하게 됩니다. (뒈지기 싫으면 어떻게든 딴 개발자 물고 늘어져야죠 뭐… 맨날 야근할겁니까… 물귀신처럼 딴놈도 같이 물고 늘어져야죠...)
다음엔 SmartSniff 나 Navicat for MySQL Friends 를 소개시켜 드리겠습니다.
ps . Adobe 나파요! ASDoc 그지 가타요!
