[Flex] ASDoc 생성 (in MXML)

정말 오랫만에 글을 쓰는 것 같네요. ;) 먹고 살기 바쁜터라 통 블로그에 신경을 못썼습니다. 그래도 꾸준히 찾아주신 분들께 감사드립니다.

이번 포스트에서는 ASDoc을 위한 작업에 대한 Tip 과 MXML 에서 ASDoc 을 작성하는 것에 대해 알아보려고 합니다. 많은 분들이 아실 만한 내용입니다만, 정리하는 차원에서 작성해보겠습니다.

우선 ASDoc 을 생성하는 방법은 지용호님의  Flex 프로젝트 문서화 - ASDoc 사용하기 라는 포스트로 알아보시면 되겠습니다. 한번 작업해보시면 아시겠지만, 콘솔에서 asdoc.exe를 실행시켜 작업하는 것이 여간 불편한 것이 아닙니다. 이미 지용호님이 그에 따른 해법으로 ANT^[각주:1]를 이용하는 방법에 대해 Flex Builder 3에서 ANT 사용하기 포스트를 해두셨습니다. (짝짝짝) 저희는 그대로 읽기만 하면 됩니다. :)
 
위의 2개의 포스트을 읽고 실습해보셨다면 '이렇게 좋은 기능이!!!' 라고 감탄하셨지 모르겠지만, ASDoc Comment를 입력하는 것 자체가 사실 좀 귀찮기는 합니다. 물론 'Ctrl + Shift + D' 를 눌러 ASDoc Comment 구문을 자동생성 할 수 있는 있습니다만, @param, @return 등을 일일이 입력하는 것 자체가 상당히 귀찮습니다. 이때 유용하게 쓸 플러그인을 하나 소개합니다.

Flex Formatter 입니다. 이미 알고 계신분이 많을 것 같습니다. 예전에 sugo님 블로그인 Apollo9 에서 Flex Builder MXML/AS Code Formatter 라는 포스트로 소개되었던 플러그인인데요, Flex Builder 3에서 가장 아쉬운 기능인 소스코드 포멧팅을 지원해주는 매우 나이스한 플러그인입니다. 이 Flex Forrmatter가 upgrade 되면서 ASDoc 관련 기능들이 추가되었습니다. 자동으로 ASDoc Comment 를 추가해주는 기능입니다.  설치방법은 우야꼬님의 블로그에 Flex Formatter - FlashBuilder Plugin 라는 포스트로 소개가 되어있으니 참고하시면 되겠습니다. (Flex Formatter는 현재 글 쓰는 시간을 기점으로 0.7.1 버전이 최신입니다.)

Flex Builder 3에서 Flex Formatter를 설치하면 위와 같이 좌측상단에 아이콘들이 추가됩니다.

총 5개의 버튼이 나타나게 되는데 간단히 설명해보면 왼쪽에서 오른쪽으로 각 버튼들은 다음과 같은 기능을 합니다.

1. 파일 내에 설정값에 따라 ASDoc Comment 생성
2. 커서가 위치한 열에 ASDoc Comment 생성
3. 코드 포멧팅 적용
4. 들여쓰기 적용
5. 코드 재배치

1번 'Generate ASDoc comments for file' 버튼을 클릭하여 ASDoc Comment를 생성하여보도록 하겠습니다.
package { import mx.core.UIComponent; public class MyClass extends UIComponent { public var goodVariable:Object; public function MyClass() { super(); } public function plus(a:int, b:int):int { return a + b; } } }
위와 같은 테스트코드를 작성 후 'Generate ASDoc comments for file' 버튼을 클릭하게 되면 아래와 같이 주석이 자동으로 생성되게 됩니다.
package { import mx.core.UIComponent; /** * * @author admin */ public class MyClass extends UIComponent { /** * * @default */ public var goodVariable:Object; /** * */ public function MyClass() { super(); } /** * * @param a * @param b * @return */ public function plus(a:int, b:int):int { return a + b; } } }
여기에 ASDoc 문서에서 볼 수 있게 설명을 아래와 같이 적어보도록 하겠습니다.
package { import mx.core.UIComponent; /** * 간단한 테스트용 클래스인 MyClass * @author admin */ public class MyClass extends UIComponent { /** * 느낌이 참 좋은 변수입니다. * @default */ public var goodVariable:Object; /** * 생성자예요! */ public function MyClass() { super(); } /** * 2개의 값을 넘겨주면 값을 더해주는 메소드입니다. * @param a 첫번째 값 * @param b 두번째 값 * @return a와 b를 더한 값 */ public function plus(a:int, b:int):int { return a + b; } } }

이렇게 작성된 클래스는 아래와 같이 ASDoc 파일이 생성됩니다.

위의 AS을 참고하여 생성된 ASDoc

하지만 아쉽게도 AS 파일에서만 지원되고, MXML에서는 아직 지원되지 않네요. ;-(


이번에는 MXML에서 ASDoc 를 생성하는 것에 대해 알아볼텐데요, MXML에서도 ASDoc Comment를 입력하면 ASDoc을 생성할 수 있습니다만, AS와는 달리 Class 수준의 Comment를 달수 없었다는 것이 문제였습니다.  (위에서 '간단한 테스트용 클래스인 MyClass'라고 출력되는 부분) 부끄럽게도 그간 ActionScript로 작성된 라이브러리에만 ASDoc을 만들었터라 MXML에서는 ASDoc을 생성해보지 않아서 해결책 찾을 생각도 안해보았는데, 이번에 한번 해보려고 열심히 구글링~ 해보았더니 떡하니 이런 문서가 있더군요!

• Adding ASDoc Comments to Flex MXML files
  
• ASDoc in MXML - Functional and Design Specification

Flex 4 에서 해당 기능이 추가되었네요. 기존의 MXML의 Comment 방식이었던 <!-- --> 과 구별하기 위해 <!--- --> (dash 3개)를 사용하게 정의하고 있네요. Flex Builder 3를 사용하시는 분들께서도 Flex 4 sdk 를 내려받으셔서 Flex 4의 asdoc.exe 를 사용하시면 위와 같이 MXML에서 Class 수준의 Comment를 입력할 수 있습니다. ;)
<?xml version="1.0"?> <!--- VBox를 상속받은 Button 모음 Class @see mx.container.VBox --> <mx:VBox xmlns:mx="http://www.adobe.com/2006/mxml"> <mx:Metadata> <![CDATA[ /** * 버튼이 선택되었을 경우 전달. */ [Event(name="myEvent", type="flash.events.Event")] ]]> </mx:Metadata> <mx:Script> <![CDATA[ /** * 컴포넌트를 초기화해주는 메소드입니다. * @param data 초기화 데이터 * @return 초기화 여부 */ public function init(data:Object):Boolean { return true; } ]]> </mx:Script> <!--- button에 대한 코멘트를 입력 --> <mx:Button id="myButton" label="This button has comment"/> </mx:VBox>

위의 MXML을 참고하여 생성된 ASDoc

Flash Builder 가 정식발매 된 후에는 당연한 듯 사용할 지도 모를 정보입니다만, 기록의 차원에서 정리하여보았습니다. ASDoc 관련 정보는 LiveDoc의 Using ASDoc에 잘 나와있으니 참고하시면 좋겠네요. ;)

1. 자바기반의 빌드 자동화 툴. (http://ant.apache.org/) [본문으로]