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

이번 포스트에서는 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 버전이 최신입니다.)


총 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 파일에서만 지원되고, 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>

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

Flex에는 크게 MXML과 ActionScript 로 구현되고 있는데, 내부적으로 MXML이 ActionScript 로 변환되어 SWF로 빌드 됩니다. MXML이 ActionScript 로 변환되는 것을 볼 수도 있는데요, keep-generated-actionscript 속성을 바꿔주면 됩니다. 속성 지정 방법은 시난님의 블로그에서 잘 정리해놓으셨습니다. (SliverLight의 경우는 Flex와 다르게 CS 코드가 XAML을 변환시키는 구조라고 하더군요)

실제로 간단하게 속성을 지정하여 변환을 하여 보면 참 새로운(이해 잘 안되는) 코드들이 마구 쏟아져나옵니다. 특정 MXML Application을 생성하면 관련된 파일 4개가 생성이 됩니다. (다른 것들은 보통 특정 스타일 지정 ActionScript 클래스이거나 속성 관련)

예를 들어 test.mxml 파일이 있다면 아래와 같이 생성이 되게 됩니다.

• test-generated.as
• test-interface.as
• _test_FlexInit-generated.as
• _test_mx_managers_System.as
  

본 포스트에서 살펴볼 것은 처음에 있는 xxx-generated.as 입니다. 이해를 쉽게 돕기 위해서 간단하게 MXML Application을 만들어보겠습니다. MXML.mxml 이라고 이름 붙혀보았습니다. (조악한 네이밍. ㅜㅜ)
<?xml version="1.0" encoding="utf-8"?> <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute"> <mx:Script> <![CDATA[ public function clickEventHandler(evt:MouseEvent):void { trace("click"); } ]]> </mx:Script> <mx:Button label="Button" click="clickEventHandler(event)" horizontalCenter="0" verticalCenter="0" /> </mx:Application>

위와 같이 MXML이 생성이 되었다면 아래와 같이 MXML-generated.as 가 생성이 됩니다.
(설명할 부분만 수록하도록 하겠습니다. - 길이가 길어서...)
// begin class def public class MXML extends mx.core.Application { // instance variables // type-import dummies // Container document descriptor private var _documentDescriptor_ : mx.core.UIComponentDescriptor = new mx.core.UIComponentDescriptor({ type: mx.core.Application , propertiesFactory: function():Object { return { childDescriptors: [ new mx.core.UIComponentDescriptor({ type: mx.controls.Button , events: { click: "___MXML_Button1_click" } , stylesFactory: function():void { this.horizontalCenter = "0"; this.verticalCenter = "0"; } , propertiesFactory: function():Object { return { label: "Button" }} }) ] }} }) // constructor (Flex display object) /** * @private **/ public function MXML() { super(); mx_internal::_document = this; // our style settings // ambient styles mx_internal::_MXML_StylesInit(); // properties this.layout = "absolute"; // events } // initialize() /** * @private **/ override public function initialize():void { mx_internal::setDocumentDescriptor(_documentDescriptor_); super.initialize(); } // scripts // <Script>, line 4 - 11 public function clickEventHandler(evt:MouseEvent):void { trace("click"); } // end scripts // supporting function definitions for properties, events, styles, effects /** * @private **/ public function ___MXML_Button1_click(event:flash.events.MouseEvent):void { clickEventHandler(event) } // initialize style defs for MXML mx_internal static var _MXML_StylesInit_done:Boolean = false; mx_internal function _MXML_StylesInit():void { // only add our style defs to the StyleManager once if (mx_internal::_MXML_StylesInit_done) return; else mx_internal::_MXML_StylesInit_done = true; var style:CSSStyleDeclaration; var effects:Array; StyleManager.mx_internal::initProtoChainRoots(); } // embed carrier vars // end embed carrier vars // end class def }

MXML Application 이기 때문에 클래스는 Application 을 상속받고 있습니다. 그 바로 밑에 보면 흔히 쓰이지 않는 UIComponentDescriptor 타입의 변수가 보입니다.


설 명이 좀 어려운데요, 다시 말해서 MXML로 정의된 정보를 모두 가지고 있게 된다는 것입니다. 내부적으로 트리형태로 자식 컴포넌트들도 다 가지고 있게 되는데, 실제로 UIComponentDescriptor 타입의 _documentDescriptor_ 변수가 Application 이고, 그 자식으로 추가된 Button 컴포넌트는 childDescriptors로 추가되어 있습니다. 물론 Button 컴포넌트도 UIComponentDescriptor 타입이 되죠. 만약 버튼에 자식 컴포넌트가 존재했다면 childDescriptors 에 정의되어 있을겁니다.

여기서 잠시 Application에 childDescriptors로 정의된 Button 을 다시 한번 보겠습니다.
new mx.core.UIComponentDescriptor({ type: mx.controls.Button , events: { click: "___MXML_Button1_click" } , stylesFactory: function():void { this.horizontalCenter = "0"; this.verticalCenter = "0"; } , propertiesFactory: function():Object { return { label: "Button" }} })
여기서 잠시 보실 것은 Button에 설정해놓은 click 이벤트입니다. 클릭시에 "___MXML_Button1_click" 를 호출하도록 되어 있는데요, 해당 메소드로 가보면 제가 정의한 clickEventHandler 를 호출하도록 하고 있습니다.
public function ___MXML_Button1_click(event:flash.events.MouseEvent):void { clickEventHandler(event) }

특정 이벤트에 대해서 이벤트 핸들러(event handler)를 설정하게 되면 1. 해당 이벤트에 대해서 호출된 메소드를 생성하고 2. 그 메소드가 이벤트 핸들러를 호출하게 하는 방식입니다.

저는 이 구조를 처음 봤을 때 전부터 궁금했던 의문점이 하나 풀렸습니다.
<?xml version="1.0" encoding="utf-8"?> <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" fontSize="12"> <mx:Script> <![CDATA[ import mx.controls.Alert; public function clickEventHandler(evt:MouseEvent, index:int):void { var message:String = "클릭한 버튼은 " + index + "번 버튼입니다."; Alert.show(message); } ]]> </mx:Script> <mx:Button x="123" y="107" label="1번 버튼" click="{clickEventHandler(event, 1)}"/> <mx:Button x="209" y="107" label="2번 버튼" click="{clickEventHandler(event, 2)}"/> </mx:Application>
위와 같은 코드가 있다고 할때에 이 것을 ActionScript 로는 어떻게 할까 하는 것이었습니다. ActionScript 로는 addEventListener 메소드를 이용해야 되는데, 핸들러 메소드에게 따로 파라미터를 던질 방법이 없었던 거죠. 커뮤니티에도 이와 같은 질문들이 가끔씩 올라왔기도 했고, 저도 상당히 궁금했었습니다.

살짝 감이 잡히시나요?
public function ___event_Button1_click(event:flash.events.MouseEvent):void { {clickEventHandler(event, 1)} } public function ___event_Button2_click(event:flash.events.MouseEvent):void { {clickEventHandler(event, 2)} }
각 버튼의 이벤트 핸들러가 생성되고 그 이벤트 핸들러에서 위에서 지정한 clickEventHandler를 호출하게 됩니다. 참 난감하더군요 ;)

아무튼 뭐 살짝 MXML이 ActionScript 로 변환되는 과정에 대해 살짝 알아보았습니다. ;)
PopupManager 관련 글은 아직 준비중입니다.. ㅜㅜ