Apple의 Documentation과 흡사한 나만의 문서화를 해봅시다!
우선 다음의 appledoc 소스를 받아서 컴파일하여 appledoc 실행 파일을 얻을 수 있습니다.
https://github.com/tomaz/appledoc
appledoc 2.0 이전까지는 html과 publish 템플릿templates 없이도 appledoc이 잘 생성되었으나 최근 버전인 2.2부터는 Templates 폴더가 반드시 필요합니다.
Templates 폴더는 docset, html, publish 이렇게 세 개의 폴더로 구성되어 있습니다.
appledoc은 GUI 애플리케이션이 아니라 Terminal.app을 열고 명령어로 입력해야 수행이 됩니다.
터미널에서 다음과 같이 명령을 입력하고 엔터를 치면 도움말을 볼 수 있습니다.
$ appledoc --help
Usage: appledoc [OPTIONS] <paths to source dirs or files>
PATHS
-o, --output <path> Output path
-t, --templates <path> Template files path
--docset-install-path <path> DocSet installation path
-s, --include <path> Include static doc(s) at path
-i, --ignore <path> Ignore given path
-x, --exclude-output <path> Exclude given path from output
--index-desc <path> File including main index description
PROJECT INFO
-p, --project-name <string> Project name
-v, --project-version <string> Project version
-c, --project-company <string> Project company
--company-id <string> Company UTI (i.e. reverse DNS name)
--- 중략 ---
보시다시피 Apple documentation 형식의 docset을 만들려면 많은 옵션들을 붙여줘야 합니다.
appledoc 소스 폴더에 보면 AppledocSettings.plist 이란 파일이 존재합니다.
AppledocSettings.plist는 위의 많은 옵션을 직접 터미널에서 입력하지 않도록 미리 필요한 사항을 입력된 상태로 appledoc을 실행할 수 있도록 도와주는 기본 설정 파일입니다.
다음의 그림을 보시면 AppledocSettings.plist의 설정 내용을 확인할 수 있습니다.
특히 Project Information에 해당하는 company-id, project-name, project-company는 반드시 입력해야 docset을 생성할 수 있습니다.
ignore에는 docset에 제외할 프로젝트 폴더 내의 파일 또는 폴더를 적어줍니다. appledoc은 기본적으로 Objective-C 소스 파일만 인식하므로 Xcode Project 파일 등을 기입할 필요는 없습니다. 문서화할 필요가 없는 외부 라이브러리 또는 프레임워크를 포함하는 폴더를 적어주면 됩니다. (위 그림의 html 폴더는 굳이 기입할 필요가 없는 폴더겠지요. 왜 적었남? ^^)
$ appledoc .
appledoc version: 2.2 (build 963)
Running for files in locations:
- .
Settings used for this run:
--project-name = LibneoBLE
--project-version = 1.0.2
--project-company = ALTERANT
--company-id = kr.alterant
--templates = /Users/me/iOS/LibneoBLE/trunk/LibneoBLE_Sources/../__AppleDoc__
--output = ../Documentation
--index-desc = (null)
--ignore = ThirdParty
--ignore = ExternalAPIs
--ignore = html
--ignore = Libraries
--ignore = Frameworks
--ignore = Testing
--docset-install-path = ../
--xcrun-path = /usr/bin/xcrun
--docset-bundle-id = kr.alterant.LibneoBLE
--docset-bundle-name = LibneoBLE Documentation
--docset-desc =
--docset-copyright = Copyright © 2014 ALTERANT Inc. All rights reserved.
--docset-feed-name = LibneoBLE Documentation
--docset-feed-url =
--docset-feed-formats = atom
--docset-package-url =
--docset-fallback-url =
--docset-publisher-id = kr.alterant.documentation
--docset-publisher-name = ALTERANT
--docset-min-xcode-version = 3.0
--docset-platform-family =
--docset-cert-issuer =
--docset-cert-signer =
--docset-bundle-filename = kr.alterant.LibneoBLE.docset
--docset-atom-filename = kr.alterant.LibneoBLE.atom
--docset-xml-filename = kr.alterant.LibneoBLE.xml
--docset-package-filename = kr.alterant.LibneoBLE-1.0.2
--clean-output = NO
--create-html = YES
--create-docset = YES
--install-docset = YES
--publish-docset = NO
--html-anchors = appledoc
--keep-intermediate-files = NO
--keep-undocumented-objects = NO
--keep-undocumented-members = NO
--search-undocumented-doc = YES
--repeat-first-par = NO
--preprocess-headerdoc = YES
--print-information-block-titles = YES
--use-single-star = NO
--merge-categories = YES
--merge-category-comment = YES
--keep-merged-sections = NO
--prefix-merged-sections = NO
--crossref-format = <?%@>?
--use-code-order = (null)
--exit-threshold = 0
--warn-missing-output-path = YES
--warn-missing-company-id = YES
--warn-undocumented-object = YES
--warn-undocumented-member = YES
--warn-empty-description = YES
--warn-unknown-directive = YES
--warn-invalid-crossref = YES
--warn-missing-arg = YES
--logformat = 1
--verbose = 3
NORMAL | Initializing...
NORMAL | Parsing source files...
NORMAL | Ignoring path './ExternalAPIs'...
NORMAL | Processing parsed data...
WARN | Invalid [[neoBLE sharedManager] reference found near neoBLE.h@118, unknown object : [neoBLE !
WARN | Invalid [[neoBLE sharedManager] reference found near neoBLE.h@151, unknown object : [neoBLE !
WARN | Invalid [notification userInfo] reference found near neoBLE.h@181, unknown object : notification !
WARN | neoBLEBeaconRangingTypeEnter is not documented!
WARN | neoBLEBeaconRangingTypeExit is not documented!
WARN | neoBLEBeaconRangingTypeDetermine is not documented!
NORMAL | Generating output...
Generation step 4/4 failed: GBDocSetInstallGenerator failed generating output, aborting!
Documentation set was installed, but couldn't reload documentation within Xcode.
Xcode got an error: No documentation set present at specified path.
NORMAL | Finished in 853ms.
output 폴더를 기입하지 않으면 기본적으로 docset은 Xcode 에 바로 인스톨이 됩니다.
Xcode 기본 docset 폴더는 다음과 같습니다.
~/Library/Developer/Shared/Documentation/DocSets
수행이 완료되면 다음과 같이 docset이 생성된 것을 확인할 수 있습니다.
docset 파일에서 마우스 우측버튼을 눌러서 Show Package Contents > Contents > Resources > Documents 폴더에 html파일이 생성된 것을 확인할 수 있습니다.
이제 index.html을 두번 클릭하면 최종 생성된 Apple Documentation을 확인할 수 있습니다.
코드 상에서 코멘트Comment를 입력하는 형식은 다음의 참고 사이트를 참고 바랍니다.
참고 사이트) https://github.com/tomaz/appledoc/blob/master/CommentsFormattingStyle.markdown
Print 
PDF
Recent Comments