documentation - lua - 文档的元数据

Question

我已经阅读了 Norman Ramsey 关于使用元数据在 lua 中生成文档的评论。

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

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

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

谢谢！

Answer 1

好吧，我想我应该回答这个问题。虽然我可能会在 2010 年 7 月 15 日之后进入可发布状态，但代码还没有准备好迎接黄金时段——并且很高兴提前分享副本。

有两个想法：

1. 每个模块都有一个名为__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等。

2. 有一个命令行工具可以抓取__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.
   

我们的服务器已关闭，但如果有机会，如果有人想使用它，我会发布此代码的链接。