Question

我读过Norman Ramsey关于using metadata for generating documentation in lua的评论。

我正在尝试从我的lib生成文档，如果可能的话我宁愿不使用luadoc。

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

欢迎其他答案，但这个问题可能是诺曼可能比其他人更好地回答。

谢谢！

Answer 1

好吧，我想我应该回答这个问题。该代码尚未准备好迎接黄金时段，尽管我可能会在2010年7月15日之后进入可释放状态 - 并且我很乐意提前分享副本。

有两个想法：

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

__doc.rfc2822_to_localtime_or_nil = [[function(date) returns number or nil
Converts RFC2822 date to local time (Unix time).
]]

第一行是该函数的“简短文档”。我希望有一天它可以动态检查，但现在它只是文档。其余的是“长篇文档”。这里有几个：

__doc.to_string = [[function(T) returns string
Converts a message to a string in RFC 2822 format.]]

__doc.to_orig_string = [[function(T) returns string
Returns the string originally used to create the message,
which may or may comply with RFC 2822.]]

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

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

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

% osbf3 internals

Documented modules:
  boot         
  cache        -- the OSBF-Lua message cache
  cfg          
  classifier   
  command_line 
  commands     
  core         
  filter       
  lists        
  log          
  mime         
  mlearn       
  msg          -- parse MIME message and manipulate headers
  options      
  output       
  roc          
  sfid         
  util         

Undocumented functions:
  core.hash           
  core.utf8tohtml     
  options.env_default

一个模块的简短概述：

: nr@yorkie 5874 ; osbf3 internals -short msg

msg: T = The representation of a message

msg.add_header = function(T, tag, contents)

msg.del_header = function(T, tag, ...)

msg.fingerprint = function(string) returns string

msg.has_sfid = function(msg.T) returns bool

msg.header_indices = function(msg, tag, ...) returns iterator

msg.headers_tagged = function(msg, tag, ...) returns iterator

msg.of_string = function(s, uncertain) returns T or nil

msg.sfid = function(msg.T, [msgspec]) returns string or calls error

msg.synopsis = function(T, w) returns string

msg.to_orig_string = function(T) returns string

msg.to_string = function(T) returns string

一个功能的文档：

% osbf3 internals msg.synopsis

msg.synopsis = function(T, w) returns string
Returns a string of width w (default 60) which is a synopsis of the
message T.  The synopsis is formed from the Subject: line and the
first few words of the body.

我们的服务器已经关闭，但是当我有机会时，如果有人想玩这个代码，我会发布这个代码的链接。

lua - 文档的元数据

1 个答案: