Apple Document Style의 문서를 만들기

1. 잘 정리된 개발 문서의 중요성

개발을 하다보면 여러가지 문제에 봉착하게 된다. 특히, 새롭게 접하는 라이브러리의 올바른 사용방법이 궁금할 때 개발문서를 찾아보거나 구글링을 통하여 솔루션을 얻게 된다. 외국, 특히, 영어권 국가들의 라이브러리를 접하다보면 개발문서가 일목요연하게 잘 정리 되어 있음을 알 수 있다. 라이브러리를 개발 & 배포하는 입장에서 잘 정리된 문서를 만드는 작업은 반드시 필요하다. 

지금까지는 xcode에서 개발을 하고 별도로 MS Word로 개발문서를 작성했는데, FacebookSDK의 문서처럼 xcode에 통합되어 Apple Document Style의 문서를 만들고 싶어져서 구글링을 해보니 "appledoc" 이라는 Tool이 존재했다. 이번글에서는 appledoc의 설치 및 사용에 관해 알아보려한다.

<Apple Document Style의 FacebookSDK의 개발 문서>

2. appledoc 설치 및 실행

appledoc은 command line tool 이다. 배포되는 방식도 binary가 아니라 소스코드 형태로 제공된다. 때문에, github에서 소스코드를 다운로드하여 xcode를 통해 컴파일 하고 적당한 위치에 이동시켜서 실행 가능하도록 만들어야한다.

Step1. GitHub에서 소스코드 다운로드

git clone https://github.com/tomaz/appledoc.git

터미널을 열고 위와 같이 입력하여 소스코드를 다운로드한다.

Step2. Install appledoc 

다운로드 받은 appledoc directory로 이동하면 "install-appledoc.sh" 파일이 있는데 실행시키면 install이 진행된다.

Step3. 문서화를 원하는 소스에 주석달기

appledoc을 통해 문서를 만들기위해서는 소스에 미리정의된 format 의 주석을 달아야지 문서화가 된다. 

주석을 만드는 방법은 아래의 링크에 예시를 참고하면된다.

참고1. http://www.cocoanetics.com/2011/11/amazing-apple-like-documentation/

참고2. http://gentlebytes.com/appledoc-docs-comments/

Step4. 문서생성 Script 작성

appledoc --help 를 실행해보면 실행 옵션이 많은것을 확인할 수 있다. 때문에 아래의 예처럼 script파일을 미리 작성해서 문서화를 진행하게 된다. appledoc 옵션에 관한 설명은 생략한다. 대신 공식홈페이지의 "Command Line Example"을 살펴보길 바란다.

<FacebookSDK for iOS의 문서 생성 script>

Step 5. 생성된 문서확인

위 처럼 문서가 생성됨을 확인할 수 있다.

3. 마치며...

멋지지 않은가?! 

첫번째 장점은 한번 저렇게 문서 생성환경을 구축해놓으면 간단히 주석만 바꿔서 재생성하면 되므로 문서화 스트레스가 줄어들이고

두번째 장점은 Apple Doc Set은 rss-feed 형태로도 제공을 해줄 수 있으므로 문서배포 자동화를 할 수 있다.

세번째 장점은 표준 iOS 문서 스타일과 일치하므로 서드파티 개발자가 배포한 라이브러리를 빠른 시간안에 살펴볼수 있을것이다.

네번째 장점은 xcode와 통합되어있어서 개발문서 접근에 용이하다.

뭐 이정도로 정리 할 수 있을것이고, 라이브러리를 배포하는 사람으로서도 기분좋은 작업이 될것이다. 끝.