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
我认为人们通常喜欢遵循示例。就像开普勒遵循参考手册的松散文档格式，并最终以 doc.css 设定了趋势，许多非开普勒项目都遵循了这种趋势（甚至罗伯托的 lpeg）。据我所知，来自开普勒一体化软件包的 Xavante 安装程序过去会生成一个 index.html 页面，链接到每个子项目的索引。除了重新格式化/重写文档，没有人会这样做，我认为添加对将几种流行格式（LuaDoc、Markdown）渲染为 HTML 的支持，并为所有已安装的项目生成一个主 index.html 页面，是我们能做到的极限。有些项目会比其他项目更好地集成，希望这能起到示范作用。--HishamMuhammad
