lua -用于文档的元数据

Question

我读了诺曼·拉姆齐写的关于using metadata for generating documentation in lua的评论。

我正在尝试从我的库中生成文档，如果可能的话，我不希望使用luadoc。

我想更多地了解这种用于生成文档的“面向元数据”的方法--方法论、示例或使用的程序。

欢迎其他答案，但这是一个诺曼可能比任何人都能回答得更好的问题。

谢谢!

Answer 1

好吧，我想我应该回答这个问题。代码还没有准备好在黄金时间，尽管我可能会在2010年7月15日之后达到可发布的状态-并且很高兴在此之前分享副本。

有两个想法：

1. 每个模块都有一个名为__doc的表。模块中的每个名称都会在__doc表中获得一个条目。下面是一个例子：

__doc.rfc2822_to_localtime_or_nil = [function( date )返回number或nil将RFC2822日期转换为本地时间(Unix时间)。]

第一行是函数的“简短文档”。我希望有一天它可以被动态检查，但现在它只是一个文档。剩下的就是“长篇文档”。下面是几个例子：

__doc.to_string = [function(T) returns string将消息转换为RFC2822格式的字符串。] __doc.to_orig_string = [function(T) returns string返回最初用于创建消息的字符串，该字符串可能或可能符合RFC2822。]

还有各种特殊的字段，比如__doc.__overview、__doc.T等等。

• 有一个命令行工具，可以搜索__doc字段并提供信息。现在这段代码不是很通用，实现起来也很混乱。但以下是一些示例输出：

整个包的概述(请注意未记录的项目列表，这对于保持我的诚实至关重要)：

% osbf3内部记录的模块:引导高速缓存-- OSBF-Lua消息高速缓存cfg分类器command_line命令核心筛选器列表日志mime mlearn msg --解析MIME消息和操纵标头选项输出roc sfid实用程序未记录的函数: core.hash core.utf8tohtml options.env_default

一个模块的简短概述：

：nr@yorkie5874；osbf3 internals -short msg msg: t=消息的表示msg.add_header =函数(T，标签，内容) msg.del_header =函数(T，标签，...)msg.fingerprint = function( string )返回字符串msg.has_sfid =function(消息)返回布尔值msg.header_indices = function(msg，tag，...)返回迭代器msg.headers_tagged = function(msg，tag，...)返回迭代器msg.of_string =函数(s，不确定)返回T或nil msg.sfid =函数(消息，消息规范)返回字符串或调用错误msg.synopsis =函数(T，w)返回字符串msg.to_orig_string =函数(T)返回字符串msg.to_string =函数(T)返回字符串

一个函数的文档：

% osbf3 internals msg.synopsis msg.synopsis = function( T，w)返回字符串返回宽度为w(默认值为60)的字符串，该字符串是邮件T的摘要。该摘要由Subject:行和正文的前几个单词组成。

我们的服务器宕机了，但当我有机会的时候，我会发布一个链接到这个代码，如果有人想玩它的话。