[Apple] appledoc으로 문서화documentation 하기

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의 설정 내용을 확인할 수 있습니다.

AppledocSettings

특히 Project Information에 해당하는 company-id, project-name, project-company는 반드시 입력해야 docset을 생성할 수 있습니다.

AppledocSettings-ignores

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이 생성된 것을 확인할 수 있습니다.

kr.alterant.LibneoBLE.docset

docset 파일에서 마우스 우측버튼을 눌러서 Show Package Contents > Contents > Resources > Documents 폴더에 html파일이 생성된 것을 확인할 수 있습니다.

kr.alterant.LibneoBLE.docset.html

 

이제 index.html을 두번 클릭하면 최종 생성된 Apple Documentation을 확인할 수 있습니다.

AppleDoc-Output-1AppleDoc-Output-2AppleDoc-Output-3

 

코드 상에서 코멘트Comment를 입력하는 형식은 다음의 참고 사이트를 참고 바랍니다.
참고 사이트) https://github.com/tomaz/appledoc/blob/master/CommentsFormattingStyle.markdown

 

[LUA] LuaDoc 설치부터 사용 경험 정리

Apple은 AppleDoc이 있고 Java에는 JavaDoc이 있어서 프로젝트 완료 후 산출물을 정리하는데 개발자의 시름을 덜어준다. 물론 전제는 개발 과정에서 충실하게 Comment를 달았다면 말이다.
 
코로나SDK를 사용해서 프로젝트를 완료했다면 Lua에는 LuaDoc이 있다.
 
 
다음의 설명은 OS X 이 설치된 장비를 기준으로 한다. (잉여력이 정말 쩐다면 윈도우머신 용으로도 만들겠지만 절대 그럴리 없을 듯 하다.)
 
루아 코드를 자동으로 문서화해주는 LuaDoc에 대해서 살펴보자!
 
LuaDoc은 lua 유틸리티에서 실행되는 lua 스크립트이다. 따라서 우선 homebrew나 macport가 설치되있어야 한다. homebrew는 http://brew.sh를 참고해서 설치할 수 있으며 macport는  http://www.macports.org를 참고해서 설치할 수 있다.
 
필자는 homebrew를 사용했다.
 
우선 lua를 다음의 명령으로 설치한다.
$ brew install lua
Warning: lua-5.1.5 already installed
LuaDoc을 설치하기 위해서는 LuaFileSystem이 설치되어야 한다.
 
LuaFileSystem을 설치하려면 luarocks가 우선 설치되어야 한다.
$ brew install luarocks
== Downloading http://luarocks.org/releases/luarocks-2.1.2.tar.gz
######################################################################## 100.0%
== Patching
patching file src/luarocks/fs/lua.lua
Hunk #1 succeeded at 741 (offset 72 lines).
== ./configure –prefix=/usr/local/Cellar/luarocks/2.1.2 –rocks-tree=/usr/local –sysconfdir=/usr/l
== make
== make install
== Caveats
Rocks install to: /usr/local/lib/luarocks/rocks

You may need to run `luarocks install` inside the Homebrew build
environment for rocks to successfully build. To do this, first run `brew sh`.
== Summary
  /usr/local/Cellar/luarocks/2.1.2: 62 files, 536K, built in 6 secon

$ luarocks install

Error: Argument missing. See ‘/usr/local/bin/luarocks help install’.
myair:luafilesystem-master neoroman$ brew sh
Your shell has been configured to use Homebrew’s build environment:
this should help you build stuff. Notably though, the system versions of
gem and pip will ignore our configuration and insist on using the
environment they were built under (mostly). Sadly, scons will also
ignore our configuration.
When done, type `exit’.

$ luarocks install luafilesystem

 

모든 설치가 완료되면 이제 luadoc을 사용할 수 있다.

 
다음은 luadoc help 이다.
$ luadoc -h
Usage: /usr/local/bin/luadoc [options|files]
Generate documentation from files. Available options are:
  -d path                      output directory path
  -t path                      template directory path
  -h, –help                   print this help and exit
      –noindexpage            do not generate global index page
      –nofiles                do not generate documentation for files
      –nomodules              do not generate documentation for modules
      –doclet doclet_module   doclet module to generate output
      –taglet taglet_module   taglet module to parse input code
  -q, –quiet                  suppress all normal output
  -v, –version                print version information

 

다음은 Lua 소스 코드에서 LuaDoc이 인식하는 Tag 리스트 이다.

Tags

LuaDoc can parse some tags at each function or table documentation. Tags are indicated in the source code with a `@‘ character followed by the name of the tag:

@author <text>
An author of the module or file.
@copyright <text>
The copyright notice of the module or file. LuaDoc adds a © sign between the label (Copyright) and the given text (e.g. 2004-2007 Kepler Project).
@field
Describe a table field definition.
@param <word> <text>
Describe function parameters. It requires the name of the parameter and its description.
@release <text>
Free format string to describe the module or file release.
@return <text>
Describe a returning value of the function. Since Lua can return multiple values, this tag should appear more than once.
@see <text>
Refers to other descriptions of functions or tables.
@usage <text>
Describe the usage of the function or variable.

Infered Tags

The following tags would be normally infered by LuaDoc, but they can be used to override the infered value.

@class <word>
If LuaDoc cannot infer the type of documentation (function, table or module definition), the programmer can specify it explicitly.
@description
The description of the function or table. This is usually infered automatically.
@name <word>
The name of the function or table definition. This is usually infered from the code analysis, and the programmer does not need to define it. If LuaDoc can infer the name of the function automatically it’s even not recomended to define the name explicitly, to avoid redundancy.
 

 

 
LuaDoc에서 인식할 수 있는 Tag가 이미 기입된 lua 소스파일이 있다면 다음의 명령으로 바로 LuaDoc output을 생성할 수 있다.
$ luadoc -d ../corona_lua_doc/  *.lua
 
 
다음은 LuaDoc Tag를 사용하는 소스 예제이다.
———————————————————————————
— @description 메인(최초 실행이 시작되는 지점)
— @release $Id: main.lua,v 1.5.0 2014/06/29 06:42:51 Henry Kim Exp $
— @author Created by Henry Kim on 6/19/14.
— @copyright Copyright (c) 2014 Alterant. All rights reserved.
————————————————————————————————————————
 
 
——————————————————————————-
— @description   네트워크 동작 여부 확인 함수
— @return 결과값이 true이면 네트워크가 연결된 상태이며 false인 경우 네트워크가 연결되지 않은 상태이다.
——————————————————————————-

LuaDoc의 Tag는 첫 행에  세 개의 대쉬(—)를 인식하면 이후는 두 개의 대쉬와 @+<키워드>로 기입하면 인식이 된다. Tag Keyword 위의 박스를 참고하자.

 
 
다음은 LuaDoc output 예시이다.
http://www.alterant.kr/?p=276
 
출력된 결과물의 index.html을 클릭하면 웹브라우져에서 위와 같은 화면을 볼 수 있다.
 
왼쪽은 파일네비게이션이고 오른쪽은 함수 목록을 표시해주고 있다. 함수에 파라미터가 있다면 자동으로 표시된다. @param 으로 설명을 기입하지 않았다면 파라미터는 리스트 형태로만 표시된다.

 

[OS X] 3D Maps in Yosemite

WWDC 2014에서 발표된 Yosemite에 Map 앱에 3D가 추가되었습니다. 아직은 아이폰에서와 같이 Bird-eye 뷰를 제공하고 있지는 않습니다.