[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 으로 설명을 기입하지 않았다면 파라미터는 리스트 형태로만 표시된다.

 

Leave a Comment


NOTE - You can use these HTML tags and attributes:
<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>