記錄 Lua 程式碼
 |
||
|
記錄 Lua 程式碼 |
|
在提供許多模組的整合文件之後，以便包含在 LuaDistributions 中，以下是我的概況... 在 tarballs（範例 [10]）中隱藏的 README 並不特別有效。Kepler 計畫導致可能稱作此「doc.css」HTML 格式流行（範例 [4]）。整體而言並不出色。它是一個有點寬鬆（不受限制）的格式，通常有效地涵蓋質化和參考 API 部分，讓人想起 Perl POD 的特點（但情況會更好，如果更多 Lua 模組以 POD 常見的 SYNOPSIS 部分開始）。值得注意的是，Lua 參考手冊也有點遵循這個寬鬆的格式。接著出現更多結構化的類別瀏覽器/JavaDoc，例如 LuaDoc（範例 [5]），不過我認為此「填空」樣式用於函式參數文件 (@param) 並不會總是鼓勵明確文件。Lua 參考手冊沒有採用此方法，而且我沒看到使用者抱怨。不過，更結構化格式的一項優點是，它允許獨立開發模組的 API 在不同格式之間系統性地相互連結，即使文件已移動或轉換為其他格式；然而，即使結構較為鬆散的 POD 也提供基本功能。幾年前我建議 Lua 以 POD 標準化 [6]，這種格式雖然有點奇怪，卻適用於 Perl 並且會適用於 Lua，但並沒有大行其道。最近，有了 Python 啟發的 reStructuredText/Sphinx（範例 [7]），它比 POD 更進一步，並提供以多種輸出格式為目標（DHTML、PDF、HTML 說明 .chm 等）。Sphinx 是一個經過驗證且支援完善的系統（例如 cmake），雖然對某些使用者來說有點過於強大，而且可能也無法在 Lua 社群中大行其道（如果真的可以的話）。Markdown 很受歡迎，尤其是對於 github 鼓勵的輕量化 README 檔案，而且 github 在 Lua 社群中正變得非常受歡迎，但對串聯 API 之類的事情來說，Markdown 有點過於輕量化。--DavidManura
最後我想說人們通常喜歡遵循範例。例如，Kepler 追隨參考手冊的鬆散文件格式，最後用 doc.css 設定了一個趨勢，許多非 Kepler 專案也追隨這個趨勢（甚至羅伯多的 lpeg 也是如此）。如果我記得沒錯，Kepler 全功能套件中的 Xavante 安裝會用來產生 index.html 頁面，連結到每個子專案的索引。除了重新格式化或撰寫文件（沒人會這麼做）之外，我想我們能做的就僅限於新增渲染為 HTML 的支援，包括幾種熱門格式（LuaDoc、Markdown），以及為所有安裝的專案產生一個主要的 index.html 頁面。有些專案整合得比其他專案好，希望這能成為一個範例。--HishamMuhammad
