lua - metadata for documentation

问题

I've read a comment from Norman Ramsey about using metadata for generating documentation in lua.

I'm attempting to generate documentation from my lib, and I'd rather not use luadoc if possible.

I'd like to know more about this "metadata-oriented" method for generating documentation - methodology, examples, or programs used.

Other answers are welcome, but this is a question that probably Norman can answer better than anyone else.

Thanks!

回答1:

Well, I suppose I should answer this. The code is not ready for prime time, although I might be able to get to to releasable state after July 15, 2010—and am happy to share copies before hand.

There are two ideas:

Every module has a table named __doc. Each name in the module gets an entry in the __doc table. Here's an example:
```
__doc.rfc2822_to_localtime_or_nil = [[function(date) returns number or nil
Converts RFC2822 date to local time (Unix time).
]]
```
The first line is the "short documentation" of the function. My hope is that one day it can get checked dynamically, but for now it is just documentation. The rest is the "long documentation". Here are a couple more:
```
__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.]]
```
There are also various special fields like __doc.__overview, __doc.T, and so on.

There's a command-line tool that crawls the __doc fields and provides information. Right now this code is not very general, and the implementation is a mess. But here are some sample outputs:

Overview of a whole package (note the list of undocumented items, which is critical to keeping me honest):

% 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

Short overview of one module:

: 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

Documentation of one function:

% 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.

Our servers are down, but when I get a chance, I'll post a link to this code if anyone wants to play with it.

来源：https://stackoverflow.com/questions/3100062/lua-metadata-for-documentation

标签

documentation

lua

luadoc