標籤
- @module 模塊, 一般一個文件就是一個模塊.
- @classmod 和 @module 類似, 但是用來描述 class, 用這個標籤後, 生成的文檔中 Module 文字會變成 Class.
- @submodule 如果一個模塊的內容被分到了好幾個文件中, 那麼就可以再其他文件中用 submodule 來定義, 後面跟上master module的名字.
- @script 和 @module 類似, 生成的文檔中 Module 文字會變成 Script.
以上幾個標籤都是project-level, 意味着每個文件中只能包含它們其中的一個, 否則生成時就會提示 Module already declared! 錯誤.
-
@author (multiple), @copyright, @license, @release 這幾個啥意思就不必說了吧, 值得一提的是它們必須放在project-level,如 @module 標籤下.
-
@function, @lfunction. 用來描述函數. @function 一般情況下不用加, 只需要給函數加上—註釋就可以.@lfunction 用來表示一個局部函數, 但是ldoc默認是不會導出局部變量和函數的.
-
@param @int, @string, @bool, @func, @tab, @thread 用來描述函數參數, 後面幾個指定了參數類型.
-
@return 函數的返回值, 函數的返回值可能有多種, 因此 @return 在一個函數中也是可以多次使用的
-
@raise 這個函數可能拋出的錯誤
-
@local 最大的作用是使得一個函數不被導出, 除非使用了(unless –all)
-
@see 引用文檔的其他內容, 同一模塊的話直接 @see xxx, 不同模塊的話需要加上模塊名 @see xxmodule.xxfunc
-
@usage 給出函數的用例, 可以分多行來寫
-
@fixme, @todo 和 @warning , 意思大家應該都懂. 但是必須在函數體內部並且以 — 開頭才能生效.
以上幾個標籤都是描述function的一些行爲的
-
@table 描述一個table, 也可以不加, 只需要給table加上—註釋就可以.
-
@field 用來描述table中的一個字段
-
@section 用來把一個模塊分隔成好幾塊
-
@type 和 @class 的作用差不多, 但不能與 @class 同時存在. 一個文件中可以有多處 @type , 會和@section 似的，把文件分隔成好多份.
-
@within 用來形容函數和table, 指定它們屬於哪個section, 可以指定不存在的一個section, 會自動創建一個
函數的一些高級用法
顯示參數的類型
函數參數@param 是不指明具體類型的, 若想指明的話可以用 @int, @string, @bool, @func, @tab, @thread 幾個標籤來.
可選參數與默認值
可選參數的標記是自參數標籤後緊跟 [opt] 來標識, 默認值則是 [opt=xx]. 讓我們看一個官方的示例:
--- a function with typed args.
-- @string name person's name
-- @int age
-- @string[opt='gregorian'] calender optional calendar
-- @int[opt=0] offset optional offset
-- @treturn string
function one (name,age,...)
end
----> displayed as: one (name, age [, calender='gregorian' [, offset=0]])
多種返回值
一個函數不同的情況可能返回不同的值, 意義也都不一樣, 那麼怎麼來表示呢? 答案是在 @return 後緊跟 x 來標識. 生成出來的文檔是用 Or 來列出這些不同的返回值的.
config.ld 的字段說明
ldoc 運行時有一堆參數可以傳遞, 在終端中去做比較麻煩, 修改也不太方便. 因此我們可以創建一個config.ld 配置文件來做這個事情, ldoc . 表示在當前目前下查找 config.ld 文件, ldoc -c path/to/myconfig.ld 讀取特殊的目錄的配置文件. 其實 config.ld 就是一個lua文件, 填寫時需要遵循lua語法.
- file 可以是一個文件名或者目錄名, 如: file = ‘test.lua’. file 也可以是一個table, 這時裏面可以填寫文件數組或目錄數組, 同時也可以包含另一個特殊的數組 exclude, 表明要排除的文件或目錄
- project 項目的名稱, 會出現在文檔的左上角. 默認爲 ldoc
- title 頁面的名稱, 默認爲 Reference
- all 導出 local 的 function
- output 導出 html 的名字, 默認是 index
- dir 導出目錄的名字, 默認是 doc
- colon 使用冒號風格代替 @ 風格的 tag
- boilerplate 忽略所有源文件中的首個註釋(塊), 比如: license 註釋.
- ext 輸出文件的後綴(默認爲 html)
- one 文檔使用單列的佈局
- style, template 指定模板和樣式的目錄. 在 config.ld 中它也可以爲 true , 表示使用和配置文件同一目錄的模板.
- merge 允許文檔從不同的文件合併同名的 module , 而不是產生多個module.