文档化 Lua 代码
 |
||
|
文档化 Lua 代码 |
|
关于为许多模块提供集成文档，供纳入 LuaDistributions，以下是我的情况概述……隐藏在 tarball 中的 README（示例 [10]）效果并不特别好。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 Help .chm 等）的目标。Sphinx 是一个经过验证且支持良好的系统（类似于 cmake），尽管对某些人来说有点重，同样，它在 Lua 社区可能不会流行（如果有什么会流行的话）。Markdown 很受欢迎，尤其是在 github 鼓励的轻量级 README 文件方面，而 github 在 Lua 社区越来越受欢迎，但 markdown 对于 API 之间的互联等内容来说有点太轻量了。--DavidManura
最终，我认为人们通常喜欢遵循示例。例如，Kepler 遵循了参考手册的宽松文档格式，并最终引领了 doc.css 的趋势，许多非 Kepler 项目（甚至 Roberto 的 lpeg）也效仿了这一点。我记得 Kepler 一体化包中的 Xavante 安装曾经生成一个 index.html 页面链接到每个子项目的索引。除了重新格式化/重写文档（这是没人愿意做的）之外，我认为添加对渲染几种流行格式（LuaDoc、Markdown）到 HTML 的支持，并为所有已安装的项目生成一个主 index.html 页面，这已是我们可以达到的最大程度。一些项目会集成得更好，希望这能起到示范作用。--HishamMuhammad
