lua - metadata for documentation

Question

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!

Cayser

Answer 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:

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

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

Clavate

The extra blank lines in the code examples arise from a bug in markdown, which Jeff has tagged 'by-design', so I think we have to assume this problem won't be fixed. – Clavate

Ooh shiny! I like the idea! thanks! Please update your answer when you are ready to share the code, otherwise I'll not know that you published it! In the meantime, answer accepted! – Cayser

you could always try <pre> blocks in place of markdown indented code blocks. This is often better for Lua since SO's and markdown don't color it very well, and is usually better for quoting program output since it isn't code at all. – Brede