lua - metadati per la documentazione

Question

Ho letto un commento da Norman Ramsey su utilizzando i metadati per la generazione di documentazione in lua .

Sto tentando di generare la documentazione dalla mia lib, e preferisco non usare luadoc se possibile.

Mi piacerebbe sapere di più su questo "metadati-oriented" Metodo per la documentazione di generazione -. Metodologia, esempi, o programmi usati

Altre risposte sono i benvenuti, ma questa è una domanda che probabilmente Norman può rispondere meglio di chiunque altro.

Grazie!

Answer 1

Bene, suppongo che dovrei rispondere a questa. Il codice non è pronto per il debutto, anche se potrei essere in grado di raggiungere a stato rilasciabile dopo 15 Luglio 2010, e sono felice di copie di condivisione prima della mano.

Ci sono due idee:

1. Ogni modulo ha una tabella denominata __doc. Ogni nome nel modulo ottiene una voce nella tabella di __doc. Ecco un esempio:

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

   La prima linea è la "breve documentazione" della funzione. La mia speranza è che un giorno si può ottenere controllare in modo dinamico, ma per ora si tratta solo di documentazione. Il resto è la "documentazione di lunga". Qui ci sono un paio di più:

   __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.]]
   

   Ci sono anche vari campi speciali come __doc.__overview, __doc.T, e così via.

2. C'è un tool a riga di comando che striscia i campi __doc e fornisce informazioni. In questo momento questo codice non è molto generale, e l'implementazione è un pasticcio. Ma qui ci sono alcune uscite di esempio:

   Panoramica di un intero pacchetto (si noti l'elenco degli elementi privi di documenti, che è fondamentale per mantenere me onesti):

   % 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 
   

   Breve panoramica di un modulo:

   : 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
   

   La documentazione di una funzione:

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

I nostri server sono giù, ma quando ho la possibilità, vi posto un link a questo codice se qualcuno vuole giocare con lui.