nezy의 IT 블로그

얼마 전에 오픈한 flex 결과물 소스에 대해서 문서화를 진행하고 있습니다.
프로젝트가 완료되고 나면 끝이 아니라 그 프로젝트에서 파생된 부가 결과물들을 공유하고 다른 프로젝트에 활용할 수 있게 하는 것이 중요합니다. 그러면 그 프로젝트에 들인 시간과 노력의 가치는 다른 사람의 시간과 노력을 절약해준 만큼 계속 더 커져 가게 되니까요. 이에 가장 중요한 것이 잘 정리된 코드와 문서입니다.

코드의 문서화는 이제 무슨무슨doc~ 시리즈를 사용하는 것이 정설처럼 굳어져 가고 있는데요. flex 나 as3 도 마찬가지입니다. asdoc 을 활용하면 되지요.

asdoc 은 javadoc 과 마찬가지로 소스코드 바로 위에 주석으로 설명을 달면 되는 방식입니다. 예를 들면 아래와 같습니다.
/**
 * 이 클래스는 이런 일도 하구요 저런 일도 해요. 그리고 할 말이 좀 있는데염. 와하하;
 * 줄을 바꿔서 적어도 한줄로 모두 나오구요. 줄 바꿈을 하고 싶으면 html 태그인 p 태그를 이용
 * 하면 되요.
 * <p>이렇게요.</p>
 * <p>근데 class 요약으로 볼 때는 맨 첫줄의 마침표까지만 코멘트가 나온답니다. 여기
 * 예제에서는 '이 클래스는 이런 일도 하구요 저런 일도 해요." 까지지요.</p>
 * <p>'그리고 할 말이 좀 있는데염. 와하하;' 부터는 class 상세 페이지로 가야만 보이지요</p>
 */
class SomeClass {

    /**
     * 이 메소드는 뭔가 일을 해염.
     * 뭐하는지 궁금하죠? 근데 이게 다 문서에 남는다고 생각하니 쑥스럽네요.
     *
     * @param1 아무 값이나 주면 되염
     * @param2 아무 값이나 주면 안되염
     * @return param1과 param2 를 가지고 이상한 Canvas 를 만들어서 리턴해주지요.
     *
     * @see FlexEvent.CREATION_COMPLETE
     */
    public function doSomething(param1:uint, param2:uint): Canvas {
        ...
        return canvas;
    }
}
귀찮아 보이죠? 하지만 하지 않으면 나중에 더 귀찮답니다. ㅠ_ㅠ

class 도 method 도 요약과 상세가 따로 있는데, 그것 구분을 마침표('.')로 한다는 것이 좀 특이한 점이었구요. 위는 as3 코드일 때 예제인데 MXML 일 때도 대동소이합니다. <mx:Script> 블럭 안에서만 된다는 점이 다르고, 또 class 레벨의 코멘트("이 클래스는 이런 일도 하구요 저런 일도 해요."라고 썼던 부분)를 MXML 에서는 할 수 없다는 점이 다른 점이네요. (요건 찾다찾다 못찾아서 adobe 의 Livedocs 에 코멘트 달았더니 바로 답변이 달리더군요. MXML 에서는 '못단다'고요.. -_-;; adobe 밉..;)

위처럼 코멘트를 달고 asdoc 프로그램을 돌리면 깔끔한 문서가 만들어지는데요. asdoc 프로그램을 사용하는 방법도 크게 3가지 정도가 있겠습니다. 걍 asdoc 프로그램을 command line 에서 직접 실행하기, flex builder 에 플러긴을 설치해서 돌리기, ant 스크립트를 짜서 asdoc 프로그램돌리기 입니다. 전 두번째 방법을 쓰다가 갑자기 플러긴이 사라져버려서.. -_-;;; 제일 원시적이지만 확실한 첫번째 방법을 쓰고 있답니다. 첫번째 방법은 지돌스타라는 분의 블로그 포스팅을 참고하면 쉽게 시작할 수 있을 겁니다. 다만 -doc-classes 를 지정해줄 때 지정해주고 싶은 class 가 여러개라면 콤마(',')로 구분해서 지정해주면 됩니다. 아래처럼요.
-doc-classes "AClass,BClass,CClass"
그리고 title 을 한글로 써주고 싶었는데, command line 에서는 cp949 로 한글이 입력되기 때문에 utf-8 을 사용하는 asdoc 에서는 잘 안되더군요. 요건 천상 다른 방법을 사용해야 합니다.

간단하게 쓰고 말려고 했는데 주절주절 말이 길어지네요. 아직 얘기하고 싶은게 더 있는데.. -_-;;
그래도 주말엔 놀아야 하니 여기서 이만.. ^^
그럼 다들 평안한 주말 보내세용 (__)

최근들어 adobe 욕이 는 nezy -.-;
신고
1 ··· 31 32 33 34 35 36 37 38 39 ··· 47 
BLOG main image
nezy의 IT 블로그
nezy가 IT 분야에서 일하면서 남기고 싶은 로그들입니다.
by nezy

공지사항

카테고리

분류 전체보기 (47)
iphone (6)

달력

«   2017/11   »
      1 2 3 4
5 6 7 8 9 10 11
12 13 14 15 16 17 18
19 20 21 22 23 24 25
26 27 28 29 30    
tistory!get rss Tistory Tistory 가입하기!

티스토리 툴바