LDoc 使用教程

LDoc 使用教程

1. 项目介绍

LDoc 是一个与 LuaDoc 兼容的文档生成器，它可以处理 Lua 源代码以及 C 扩展源代码。LDoc 支持使用 Markdown 渲染注释，同时还能集成 README 文档和格式化打印的示例文件。该工具旨在提供比 LuaDoc 更好的诊断功能，例如，如果无法找到 @see 引用，LDoc 会给出引用的行号。此外，LDoc 还支持不使用 module() 函数的模块，这对于 Lua 5.2 中已经弃用的函数尤其重要。

2. 项目快速启动

首先，确保安装了 Penlight 和 LuaFileSystem，这些是 LDoc 的依赖项。可以从 LuaRocks 安装 Penlight：

luarocks install penlight

然后，从 GitHub 下载 LDoc 源代码，并创建一个指向 ldoc.lua 的别名：

lua /path/to/ldoc/ldoc.lua $*

或者创建一个批处理文件 ldoc.bat：

@echo off
lua \path\to\ldoc\ldoc.lua %*

接下来，生成文档的命令如下：

ldoc .

这将在当前目录下生成文档。

3. 应用案例和最佳实践

代码注释

使用 LDoc 生成文档时，应该按照以下格式编写代码注释：

--- 模块或函数的摘要。
-- 描述信息，可以跨越多行。
-- @param p1 第一个参数的描述
-- @param p2 第二个参数的描述
-- @return 返回值的描述
-- @see 参考的其他函数或模块
function mod1.first_fun(p1, p2)
    -- 实现代码
end

集成 README 文档

在项目根目录下，可以创建一个 config.ld 文件来配置 LDoc，例如：

project = "项目名称"
description = "项目描述"
title = "项目文档"
output = "doc"
dir = "doc"

然后，在 ldoc 命令中指定配置文件：

ldoc --config config.ld

4. 典型生态项目

LDoc 适用于需要文档化的 Lua 项目，特别是那些希望使用 Markdown 渲染注释的项目。例如，Penlight 项目就是使用 LDoc 生成文档的一个典型例子，它展示了如何利用 LDoc 生成高质量的文档。其他使用 LDoc 的项目包括各种 Lua 库和框架，它们通过 LDoc 提供清晰的 API 文档和用户指南。